App Builder Connector Setup

Guide users through Adobe App Builder connector setup. Act as the interactive UI for Options 1 and 2 by running non-interactive commands and asking explicit choices. Hand off Option 3 to terminal onboarding.

Connector Type Mapping

Resolve template names internally. Do not ask users to type template package names.

Connector Type	Template Name
Translate	`@adobe/generator-app-excshell`

Connector Type Inference Rule

Infer connector type from the user's first request when explicit.

If user says set-up translate connector for me (or equivalent), set type to Translate and do not ask connector-type question.
If user says only set-up connector for me (type not specified), ask connector-type question in Step 1.3.

Required Order

Follow this order without reordering:

Phase 0: Developer Console guidance
Phase 0.1: Project exists gate
Prerequisites check
Authentication preflight
Phase 1: Entry question
Option 1, 2, or 3

Never request workspace JSON before authentication succeeds.

AskQuestion Rule

When using AskQuestion, wait for the user response and continue from the matching branch in the next turn.

Phase 0: Developer Console Setup

Instruct user to verify they already created an App Builder project:

Go to https://developer.adobe.com/console
Select organization
Create project from template (App Builder)
Open a workspace (Stage or Production)

Phase 0.1: Project Exists Gate

Use AskQuestion:

Prompt: Have you created an App Builder project already in Adobe Developer Console?
Options: Yes, No

Branch:

Yes: continue to prerequisites.
No: stop flow and ask user to create project first.

Prerequisites Check

Run:

node --version
npm --version
aio --version

If Node is missing or <20, use AskQuestion with:

Install via nvm (recommended)
Install via Homebrew (macOS)
Install manually

Handle each branch:

nvm:

nvm install 20
nvm use 20

Homebrew:

brew install node@20

Manual: point to https://nodejs.org/, wait for confirmation.

Verify with node --version before continuing.

If AIO CLI is missing:

npm install -g @adobe/aio-cli
aio --version

Continue to authentication preflight only after prerequisites pass.

Authentication Preflight

CI environment check (required first step): Before running any auth command, check whether CI=1 is set:

echo "CI=${CI}"

If CI=1, the IMS Auth SDK will block interactive login entirely (no URL, just an error). This happens in Cursor's agent shell. In that case, prefix ALL auth commands with env CI= to unset it for that invocation.

Run in foreground and wait for completion:

# Standard (non-CI shell):
aio auth login --open

# Cursor agent shell (CI=1 is injected automatically):
env CI= aio auth login --open

Treat auth output as sensitive; do not echo raw token values.

Interpretation:

Success: continue.
Waiting with manual login URL: capture URL and run:

open "<capturedLoginUrl>"

Then keep waiting for the original auth command to exit.

Failure or timeout: retry once with:

# Standard:
aio auth login --force --no-open

# Cursor agent shell:
env CI= aio auth login --force --no-open

If retry shows login URL, run open "<capturedLoginUrl>" and wait.

Environment notes:

If auth writes outside workspace and fails permission checks (for example ~/.config/aio), rerun with elevated permissions.
If open fails because of sandbox/GUI limits, rerun open with elevated permissions.
Cursor agent shell always sets CI=1, NO_COLOR=1, and TERM=dumb. Use env CI= prefix on all aio auth commands when running inside Cursor.

If both login attempts fail, stop setup and hand off:

npx appbuilder-connector-interactive-onboarding

Do not request workspace JSON after auth failure.

Phase 1: Entry Question

Run only after authentication passes.

Use AskQuestion:

Prompt: Do you have the workspace config JSON downloaded from Adobe Developer Console?
Options:

Yes, I'll share the file path
No — how do I download it?
No — I want to set it up interactively

Branch:

Option 1 -> Option 1 (JSON Path)
Option 2 -> Option 2 (Download Guide)
Option 3 -> Option 3 (Interactive Script)

Option 1: JSON Path (Agent-Driven)

Step 1.1: Request JSON

Ask for either:

JSON file path (example: ~/Downloads/MyProject-393012-Stage.json)
JSON content pasted in chat or shared by @ reference

Step 1.2: Read and Confirm JSON

Read JSON and extract:

project.org.name
project.name
project.workspace.name

Confirm with AskQuestion:

Prompt: Configuring for Organization: [org], Project: [project], Workspace: [workspace]. Proceed with this workspace config?
Options:

Yes, continue
No, I'll provide a different JSON

Branch:

Yes: continue.
No: return to Step 1.1.

Do not rerun auth unless user reports auth errors.

Step 1.3: Select Connector Type

If connector type is already explicit in user request (for example translate), skip this step and use that type. Otherwise use AskQuestion:

Prompt: What type of connector are you building?
Options: Translate

Resolve template from mapping table internally.

Step 1.4: Choose Target Directory

Set target directory automatically to ./<project-name-lowercase>, announce it, then ensure it exists:

mkdir -p <targetDir>

Step 1.5: Pre-seed Workspace Config (Required)

Run before aio app init:

aio app use <jsonPath> --merge --no-input

Run in working_directory: "<targetDir>".

Step 1.6: Scaffold

Run:

aio app init <targetDir> --template <templateName> --yes --import <jsonPath>

If the runner supports non-blocking execution, poll until command exit. After completion, verify <targetDir>/app.config.yaml exists.

Step 1.7: Install Dependencies

Run in <targetDir>:

npm install

If install fails, suggest npm cache clean --force and retry.

Step 1.8: Complete

Report completion and provide next commands without auto-running:

cd <targetDir>
aio app dev
aio app run
aio app deploy

Option 2: Download Guide

Provide download steps:

Open https://developer.adobe.com/console
Select organization
Open project
Open workspace in left sidebar
Click Download All
Share JSON path or JSON contents

When JSON arrives, continue with Option 1 from Step 1.2.

Option 3: Interactive Script

Hand off and stop:

npx appbuilder-connector-interactive-onboarding

Tell user to return for deployment, troubleshooting, or post-setup help.

Post-Setup Command Guidance

Default to guidance-first. Do not auto-run long-lived commands (aio app dev, aio app run) unless user explicitly asks.

Common commands:

aio app dev
aio app run
aio app deploy
aio app undeploy
aio app logs

Configuration Management

View current selections:

aio console org selected
aio console project selected
aio console workspace selected

Switch workspace:

aio console workspace list --json
aio console workspace select <workspaceId>
aio console workspace dl /tmp/workspace-config.json
aio app use /tmp/workspace-config.json --merge --no-input

Switch project:

aio console project list --json
aio console project select <projectId>

Switch organization:

aio console org list --json
aio console org select <orgId>

Clear and re-authenticate:

aio auth logout
aio auth login

If login fails, force refresh:

aio auth logout
aio auth login --force