4.0.0 • Published 2d ago

@adobe-thillai/aio-cli-plugin-ccdx

Licence

Apache-2.0

Version

4.0.0

Deps

Size

863 kB

Vulns

Weekly

Summary Dependency Versions

Commerce Compass

An Adobe App Builder SPA that installs the Claude Code AI toolkit into your Adobe Commerce or App Builder project — step by step, running entirely on your local machine.

How it works

Commerce Compass is a two-part system:

Part	What it does
App Builder SPA (`aio app dev`)	Wizard UI — collects platform, role, starter kit, and project path
Local bridge (`npm run bridge`)	Background server on `localhost:3131` — executes `setup.sh` and streams 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`
AIO CLI	latest	`npm install -g @adobe/aio-cli`
git	any	`git --version`
Claude Code	latest	claude.ai/code

Quick start

Two terminals, both from the commerce-compass directory:

# Terminal 1 — bridge (runs setup.sh on your machine)
npm run bridge

# Terminal 2 — SPA dev server
npm start

Open the URL printed by npm start (typically https://localhost:9080), complete the wizard, and click Run Setup on this machine.

Wizard steps

1. Platform

Option	Toolkit installed
Adobe Commerce	`adobe-commerce-ai-toolkit`
App Builder	`adobe-appbuilder-ai-toolkit`

2. Starter Kit (App Builder 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. Role

Role	Access
Developer	Phase 3 (implement) + Phase 4 (validate)
Lead	Phase 2 (structure) + Phase 3 + Phase 4
Architect	All phases 1–4

4. Project path

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

5. Preview & run

Summarises your config. If the bridge is running, click Run Setup on this machine to install. Live terminal output streams directly in the browser.

What gets installed

Adobe Commerce

Into your project directory (.claude/):

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

App Builder

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 (platform, role, starter kit)
.codegraph/ — code intelligence index (symbols, call paths, blast-radius graph)

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

Open your project in Claude Code
Run /commerce-init (Commerce) or /appbuilder-init (App Builder) to verify the setup
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: platform → [starter-kit] → role → project-path → preview
  │
  │  GET  localhost:3131/api/health   — bridge check on mount
  │  POST localhost:3131/run          — streams setup.sh output via SSE
  ▼
setup-server.js (localhost:3131)
  │
  └─ spawn bash setup.sh --non-interactive --platform … --project … --role … [--starter-kit …]
       │
       ├─ ensure toolkit cached at ~/.commerce-compass/packages/
       │    └─ sparse clone from GitHub on first run, git pull on subsequent runs
       │
       ├─ node <toolkit>/scripts/setup-project.mjs --project … --role …
       │    ├─ copies .claude/ commands, hooks, settings, CLAUDE.md into project
       │    └─ setupCodegraph(projectRoot)   ← automatic for all three toolkits
       │         ├─ npm install -g @colbymchenry/codegraph  (skip if already installed)
       │         ├─ wire ~/.claude.json mcpServers.codegraph entry
       │         └─ codegraph init  (build SQLite index in .codegraph/)
       │
       ├─ [App Builder only] git clone starter kit as sibling to project
       │
       └─ write .commerce-compass config into project root

License

Apache-2.0