{"_id":"@adobe-thillai/commerce-compass","name":"@adobe-thillai/commerce-compass","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@adobe-thillai/commerce-compass","version":"1.0.0","description":"Local bridge for the Commerce Compass setup wizard — installs a Claude Code Commerce Upgrade, Commerce PaaS Development, or App Builder toolkit into your project, selected via the hosted wizard UI.","author":{"name":"Thillai Prabu"},"license":"Apache-2.0","bin":{"commerce-compass":"bin/commerce-compass.js"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"peerDependencies":{"@adobe/aio-lib-ims":">=3.0.0"},"scripts":{"prestart":"lsof -ti :35729 2>/dev/null | xargs kill -9 2>/dev/null; lsof -ti :9080 2>/dev/null | xargs kill -9 2>/dev/null; sleep 1","start":"aio app dev","bridge":"node setup-server.js","bridge:stop":"lsof -ti :3131 2>/dev/null | xargs kill -9 2>/dev/null; true","build":"aio app build","deploy":"aio app deploy","undeploy":"aio app undeploy"},"dependencies":{"fs-extra":"^11.0.0"},"devDependencies":{"@adobe/aio-sdk":"^6.0.0","@adobe/react-spectrum":"^3.0.0","@spectrum-icons/workflow":"^4.2.0","react":"^18.0.0","react-dom":"^18.0.0"},"keywords":["adobe-commerce","adobe-app-builder","commerce-compass"],"_id":"@adobe-thillai/commerce-compass@1.0.0","gitHead":"a535ae6c93703bffd7e673dda30768c6c0585cbd","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-Qgu0RBSMGS9piicJb+EXFlyTfr9zEavr5XM01tUvUyTPofmjMhNx3P/a+bkY6bOGzIkYH/cRP1FKJDTV19bkTg==","shasum":"c4b06f20286bd93f216be0801cc309ffa8c357a5","tarball":"https://registry.npmjs.org/@adobe-thillai/commerce-compass/-/commerce-compass-1.0.0.tgz","fileCount":27,"unpackedSize":105454,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDO+ZpJUc4lwu12tPAvNtnGn3GGTnwgUuqZ21THQP0A1AiEA6e5BRjOiQ6XNN3vasuG8azFhFc0nKIwp+2tk9wHozCA="}]},"_npmUser":{"name":"trajendran","email":"trajendran@adobe.com"},"directories":{},"maintainers":[{"name":"trajendran","email":"trajendran@adobe.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/commerce-compass_1.0.0_1785832766142_0.3118075688008968"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-04T08:39:26.000Z","1.0.0":"2026-08-04T08:39:26.282Z","modified":"2026-08-04T08:39:26.538Z"},"maintainers":[{"name":"trajendran","email":"trajendran@adobe.com"}],"description":"Local bridge for the Commerce Compass setup wizard — installs a Claude Code Commerce Upgrade, Commerce PaaS Development, or App Builder toolkit into your project, selected via the hosted wizard UI.","keywords":["adobe-commerce","adobe-app-builder","commerce-compass"],"author":{"name":"Thillai Prabu"},"license":"Apache-2.0","readme":"# Commerce Compass\n\nA hosted Adobe App Builder SPA that installs a Claude Code Commerce/App Builder toolkit\n(`ccua`, `ccca`, or `ccma` — each npm-installed on demand) into your project. No repo access\nneeded — anyone with the SPA URL can use it via `npx @adobe-thillai/commerce-compass`.\n\n---\n\n## How it works\n\nCommerce Compass is a two-part system:\n\n| Part | What it does |\n|------|-------------|\n| **App Builder SPA** (hosted, or `aio app dev` locally) | Wizard UI — collects the toolkit, project state (ccua), starter kit, and project path |\n| **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 |\n\nThe 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.\n\n---\n\n## Prerequisites\n\n| Tool | Version | Check |\n|------|---------|-------|\n| Node.js | ≥ 18 | `node --version` |\n| git | any | `git --version` |\n| Claude Code | latest | [claude.ai/code](https://claude.ai/code) |\n\n`npx` ships with Node.js — no separate install, no `aio` CLI, no repo access needed for the\nend-user path below.\n\n---\n\n## Quick start\n\n1. Open the hosted SPA URL.\n2. If it shows \"Start the local bridge first,\" run this in your terminal:\n   ```bash\n   npx @adobe-thillai/commerce-compass\n   ```\n3. The page detects the bridge automatically — complete the wizard and click **Run Setup on this machine**.\n\n### For Commerce Compass maintainers (local development)\n\n**Two terminals, both from a `commerce-compass` checkout:**\n\n```bash\n# Terminal 1 — bridge\nnpm run bridge\n\n# Terminal 2 — SPA dev server (requires the aio CLI: npm install -g @adobe/aio-cli)\nnpm start\n```\n\nOpen the URL printed by `npm start` (typically `https://localhost:9080`).\n\n---\n\n## Wizard steps\n\n### 1. Toolkit\n\n| Option | npm package installed |\n|--------|-----------------|\n| Commerce Upgrade Toolkit | [`@adobe-thillai/aio-cli-plugin-ccua`](https://www.npmjs.com/package/@adobe-thillai/aio-cli-plugin-ccua) |\n| Commerce PaaS Development Toolkit | [`@adobe-thillai/aio-cli-plugin-ccca`](https://www.npmjs.com/package/@adobe-thillai/aio-cli-plugin-ccca) |\n| App Builder Toolkit / ACCS Migration | [`@adobe-thillai/aio-cli-plugin-ccma`](https://www.npmjs.com/package/@adobe-thillai/aio-cli-plugin-ccma) |\n\nEach 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.\n\n### 2. Starter Kit _(App Builder / ACCS Migration only)_\n\n| Option | What gets cloned |\n|--------|-----------------|\n| Integration | `adobe/commerce-integration-starter-kit` (contents merged into your project root) |\n| Checkout | `adobe/commerce-checkout-starter-kit` (contents merged into your project root) |\n| Not applicable | Skip — for existing or standalone apps |\n\n### 3. Project path\n\nAbsolute path to your existing project directory (must start with `/`).\n\n### 4. Preview & run\n\nSummarises 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.\n\n---\n\n## What gets installed\n\n### Commerce Upgrade Toolkit (`ccua`) / Commerce PaaS Development Toolkit (`ccca`)\n\nInto your project directory (`.claude/`):\n\n- `CLAUDE.md` — full domain knowledge and SDLC procedures\n- `.claude/commands/` — phase commands (`/phase1` → `/phase4`, `/dev-feature`, `/upgrade-hop`, `/review`, `/deploy-check`, …)\n- `.claude/hooks/` — quality and audit hooks\n- `.claude/settings.json` — pre-authorised tool permissions (includes `mcp__codegraph__*`)\n- `.commerce-compass` — config file (toolkit, role)\n- `requirements/REQUIREMENTS.md` — project info template\n- `.codegraph/` — code intelligence index (symbols, call paths, blast-radius graph)\n\n### App Builder Toolkit / ACCS Migration (`ccma`)\n\nInto your project directory (`.claude/`):\n\n- `CLAUDE.md` — App Builder domain knowledge and workflow\n- `.claude/commands/` — App Builder phase commands\n- `.claude/hooks/` — quality hooks\n- `.claude/settings.json` — pre-authorised tool permissions (includes `mcp__codegraph__*`)\n- `.commerce-compass` — config file (toolkit, role, starter kit)\n- `.codegraph/` — code intelligence index (symbols, call paths, blast-radius graph)\n\n---\n\n## Code Intelligence (CodeGraph)\n\nEvery toolkit installation automatically sets up [CodeGraph](https://github.com/colbymchenry/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.\n\n### What happens at install time\n\nThe setup script runs three steps after copying toolkit files — all warn-and-continue on failure, never blocking the rest of setup:\n\n| Step | Action |\n|------|--------|\n| Install | `npm install -g @colbymchenry/codegraph` |\n| Wire | Adds `mcpServers.codegraph` entry to `~/.claude.json` |\n| Index | Runs `codegraph init` in your project root |\n\n### What developers get\n\n- `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\n- `mcp__codegraph__*` pre-approved in `.claude/settings.json` — no per-call permission prompts\n- `.codegraph/` index in the project root — kept current by the built-in file watcher\n\n### Verify the setup\n\n```bash\ncodegraph --version\ngrep -A3 '\"codegraph\"' ~/.claude.json\nls .codegraph/\n```\n\n### Manual setup (if auto-install failed)\n\n```bash\nnpm install -g @colbymchenry/codegraph\ncodegraph init\n```\n\nThen add to `~/.claude.json` under `mcpServers`:\n```json\n\"codegraph\": {\n  \"type\": \"stdio\",\n  \"command\": \"codegraph\",\n  \"args\": [\"serve\", \"--mcp\"]\n}\n```\n\n---\n\n## After setup\n\n1. Open your project in Claude Code\n2. Run `/upgrade-hop` (Commerce Upgrade), `/commerce-init` (Commerce PaaS Development), or `/appbuilder-init` (App Builder / ACCS Migration) to verify the setup\n3. Start with the command matching your role:\n   - Architect: `/phase1`\n   - Lead: `/phase2`\n   - Developer: `/phase3`\n\n---\n\n## npm scripts\n\n| Script | What it does |\n|--------|-------------|\n| `npm start` | Start SPA dev server (`aio app dev`) |\n| `npm run bridge` | Start local bridge server on port 3131 |\n| `npm run bridge:stop` | Kill the bridge server |\n| `npm run build` | Build SPA for deployment |\n| `npm run deploy` | Deploy SPA to Adobe App Builder Stage |\n| `npm run undeploy` | Remove deployed SPA |\n\n---\n\n## Troubleshooting\n\n**\"Local bridge not running\" in the SPA**\n\nStart the bridge in a separate terminal:\n```bash\nnpm run bridge\n```\nThen click **Retry** in the SPA.\n\n**Port already in use**\n\n```bash\nnpm run bridge:stop   # kill port 3131\n# or for the SPA dev server:\nlsof -ti :35729 :9080 | xargs kill -9\n```\n\n**Setup fails mid-run**\n\nCheck the terminal output streamed in the SPA. The most common causes:\n- Toolkit repo not accessible (check your network / GitHub access)\n- Project path does not exist on disk\n- Node.js version below 18\n\nClick **Retry** after fixing the issue.\n\n**`aio app dev` binds to wrong org**\n\n```bash\naio config:clear\naio logout\naio login\naio console org select\naio console project select\naio console workspace select\naio app use\n```\n\n---\n\n## Architecture\n\n```\nbrowser (App Builder SPA)\n  │  wizard: toolkit (ccua|ccca|ccma) → [starter-kit] → project-path → preview\n  │\n  │  GET  localhost:3131/api/health   — bridge check on mount\n  │  POST localhost:3131/run          — streams install output via SSE\n  ▼\nsetup-server.js (localhost:3131)\n  │\n  └─ installToolkit({ platform, project, docs, starterKit }, pluginRoot, send)\n       │\n       ├─ npm install --no-save --prefix <scratch-tmp-dir> <@adobe-thillai/aio-cli-plugin-ccXX>@latest\n       │\n       ├─ node <tmp-dir>/node_modules/<pkg>/scripts/setup-project.mjs --project … --role …\n       │    ├─ copies .claude/ commands, hooks, settings, CLAUDE.md into project\n       │    └─ setupCodegraph(projectRoot)   ← automatic for every toolkit\n       │         ├─ npm install -g @colbymchenry/codegraph  (skip if already installed)\n       │         ├─ wire ~/.claude.json mcpServers.codegraph entry\n       │         └─ codegraph init  (build SQLite index in .codegraph/)\n       │\n       ├─ [ccma only] git clone starter kit as sibling to project\n       │\n       ├─ remove the scratch temp dir\n       │\n       └─ write .commerce-compass config into project root\n```\n\nThe hidden \"Full Program\" combo (Commerce + App Builder + Orchestrator) has no\npublished npm package yet — its install path still resolves the bundled\n`packages/adobe-program-orchestrator-toolkit/` directory and is reachable only\nvia direct API/CLI invocation, not from the wizard UI.\n\n---\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md","_rev":"1-f3bcbe8e63ce49b3c21777f04085f0e7"}