Commerce Compass

A hosted Adobe App Builder SPA that installs a Claude Code Commerce/App Builder toolkit (ccua, ccca, or ccma — each npm-installed on demand) into your project. No repo access needed — anyone with the SPA URL can use it via npx @adobe-thillai/commerce-compass.

How it works

Commerce Compass is a two-part system:

| Part | What it does | |------|-------------| | App Builder SPA (hosted, or aio app dev locally) | Wizard UI — collects the toolkit, project state (ccua), starter kit, and project path | | Local bridge (npx @adobe-thillai/commerce-compass, or npm run bridge in a checkout) | Background server on localhost:3131 — npm-installs the selected toolkit and runs its setup script, streaming output back to the SPA |

The SPA cannot write to your filesystem directly (App Builder SPAs run in the browser). The bridge server handles that, streaming live terminal output back so you can see exactly what's happening.

Prerequisites

| Tool | Version | Check | |------|---------|-------| | Node.js | ≥ 18 | node --version | | git | any | git --version | | Claude Code | latest | claude.ai/code |

npx ships with Node.js — no separate install, no aio CLI, no repo access needed for the end-user path below.

Quick start

1. Open the hosted SPA URL.
2. If it shows "Start the local bridge first," run this in your terminal:

   npx @adobe-thillai/commerce-compass

3. The page detects the bridge automatically — complete the wizard and click Run Setup on this machine.

For Commerce Compass maintainers (local development)

Two terminals, both from a commerce-compass checkout:

# Terminal 1 — bridge
npm run bridge

# Terminal 2 — SPA dev server (requires the aio CLI: npm install -g @adobe/aio-cli)
npm start

Open the URL printed by npm start (typically https://localhost:9080).

Wizard steps

1. Toolkit

| Option | npm package installed | |--------|-----------------| | Commerce Upgrade Toolkit | @adobe-thillai/aio-cli-plugin-ccua | | Commerce PaaS Development Toolkit | @adobe-thillai/aio-cli-plugin-ccca | | App Builder Toolkit / ACCS Migration | @adobe-thillai/aio-cli-plugin-ccma |

Each package is npm-installed on demand into a scratch temp directory (never into your project's own node_modules/package.json), and cleaned up once setup finishes.

2. Starter Kit (App Builder / ACCS Migration only)

| Option | What gets cloned | |--------|-----------------| | Integration | adobe/commerce-integration-starter-kit (contents merged into your project root) | | Checkout | adobe/commerce-checkout-starter-kit (contents merged into your project root) | | Not applicable | Skip — for existing or standalone apps |

3. Project path

Absolute path to your existing project directory (must start with /).

4. Preview & run

Summarises your config — including the resolved npm package and version. If the bridge is running, click Run Setup on this machine to install. Live terminal output streams directly in the browser.

What gets installed

Commerce Upgrade Toolkit (ccua) / Commerce PaaS Development Toolkit (ccca)

Into your project directory (.claude/):

• CLAUDE.md — full domain knowledge and SDLC procedures
• .claude/commands/ — phase commands (/phase1 → /phase4, /dev-feature, /upgrade-hop, /review, /deploy-check, …)
• .claude/hooks/ — quality and audit hooks
• .claude/settings.json — pre-authorised tool permissions (includes mcp__codegraph__*)
• .commerce-compass — config file (toolkit, role)
• requirements/REQUIREMENTS.md — project info template
• .codegraph/ — code intelligence index (symbols, call paths, blast-radius graph)

App Builder Toolkit / ACCS Migration (ccma)

Into your project directory (.claude/):

• CLAUDE.md — App Builder domain knowledge and workflow
• .claude/commands/ — App Builder phase commands
• .claude/hooks/ — quality hooks
• .claude/settings.json — pre-authorised tool permissions (includes mcp__codegraph__*)
• .commerce-compass — config file (toolkit, role, starter kit)
• .codegraph/ — code intelligence index (symbols, call paths, blast-radius graph)

Code Intelligence (CodeGraph)

Every toolkit installation automatically sets up CodeGraph — a SQLite knowledge graph that indexes every symbol, call path, and file dependency in your project, giving Claude Code instant structural understanding without reading files one by one.

What happens at install time

The setup script runs three steps after copying toolkit files — all warn-and-continue on failure, never blocking the rest of setup:

| Step | Action | |------|--------| | Install | npm install -g @colbymchenry/codegraph | | Wire | Adds mcpServers.codegraph entry to ~/.claude.json | | Index | Runs codegraph init in your project root |

What developers get

• codegraph_explore tool available in every Claude Code session — returns verbatim, line-numbered source for any symbol plus its call graph and blast-radius summary
• mcp__codegraph__* pre-approved in .claude/settings.json — no per-call permission prompts
• .codegraph/ index in the project root — kept current by the built-in file watcher

Verify the setup

codegraph --version
grep -A3 '"codegraph"' ~/.claude.json
ls .codegraph/

Manual setup (if auto-install failed)

npm install -g @colbymchenry/codegraph
codegraph init

Then add to ~/.claude.json under mcpServers:

"codegraph": {
  "type": "stdio",
  "command": "codegraph",
  "args": ["serve", "--mcp"]
}

After setup

1. Open your project in Claude Code
2. Run /upgrade-hop (Commerce Upgrade), /commerce-init (Commerce PaaS Development), or /appbuilder-init (App Builder / ACCS Migration) to verify the setup
3. Start with the command matching your role:
   • Architect: /phase1
   • Lead: /phase2
   • Developer: /phase3

npm scripts

| Script | What it does | |--------|-------------| | npm start | Start SPA dev server (aio app dev) | | npm run bridge | Start local bridge server on port 3131 | | npm run bridge:stop | Kill the bridge server | | npm run build | Build SPA for deployment | | npm run deploy | Deploy SPA to Adobe App Builder Stage | | npm run undeploy | Remove deployed SPA |

Troubleshooting

"Local bridge not running" in the SPA

Start the bridge in a separate terminal:

npm run bridge

Then click Retry in the SPA.

Port already in use

npm run bridge:stop   # kill port 3131
# or for the SPA dev server:
lsof -ti :35729 :9080 | xargs kill -9

Setup fails mid-run

Check the terminal output streamed in the SPA. The most common causes:

• Toolkit repo not accessible (check your network / GitHub access)
• Project path does not exist on disk
• Node.js version below 18

Click Retry after fixing the issue.

aio app dev binds to wrong org

aio config:clear
aio logout
aio login
aio console org select
aio console project select
aio console workspace select
aio app use

Architecture

browser (App Builder SPA)
  │  wizard: toolkit (ccua|ccca|ccma) → [starter-kit] → project-path → preview
  │
  │  GET  localhost:3131/api/health   — bridge check on mount
  │  POST localhost:3131/run          — streams install output via SSE
  ▼
setup-server.js (localhost:3131)
  │
  └─ installToolkit({ platform, project, docs, starterKit }, pluginRoot, send)
       │
       ├─ npm install --no-save --prefix <scratch-tmp-dir> <@adobe-thillai/aio-cli-plugin-ccXX>@latest
       │
       ├─ node <tmp-dir>/node_modules/<pkg>/scripts/setup-project.mjs --project … --role …
       │    ├─ copies .claude/ commands, hooks, settings, CLAUDE.md into project
       │    └─ setupCodegraph(projectRoot)   ← automatic for every toolkit
       │         ├─ npm install -g @colbymchenry/codegraph  (skip if already installed)
       │         ├─ wire ~/.claude.json mcpServers.codegraph entry
       │         └─ codegraph init  (build SQLite index in .codegraph/)
       │
       ├─ [ccma only] git clone starter kit as sibling to project
       │
       ├─ remove the scratch temp dir
       │
       └─ write .commerce-compass config into project root

The hidden "Full Program" combo (Commerce + App Builder + Orchestrator) has no published npm package yet — its install path still resolves the bundled packages/adobe-program-orchestrator-toolkit/ directory and is reachable only via direct API/CLI invocation, not from the wizard UI.

License

Apache-2.0