SuiteCommerce Theme Developer Tools — Sandbox Setup Runbook

Purpose: stand up the SC Theme Developer Tools against the RBD Sandbox so we can clone the active theme and deploy the Athos front-end overrides. Who runs it: Cole (needs NetSuite Sandbox login + admin to create an integration record). Claude guides. Sources: Oracle "Set Up Theme Developer Tools" + "Gulp Command Reference" (links at bottom).

Prerequisites (account side — should already be true, verify)

• SuiteCommerce (Standard) installed on the account ✅ (site is live)
• SuiteCommerce Extension Manager installed (verify in Sandbox)
• Local: Node.js + Gulp.js installed (node -v, gulp -v to check)

Step 1 — Download the tools from the Sandbox

1. Log in to the Sandbox NetSuite account
2. Documents > Files > File Cabinet → SuiteBundles/Bundle 521562/
3. Download ThemeDevelopmentTools-26.1.x.zip (latest minor; NOT the 18.2.1 Aconcagua one)
4. Extract to a dedicated sandbox dir — Oracle explicitly says keep prod and sandbox in separate root directories. Suggest: ~/ai-projects-local/rbd-sc-theme-sandbox/
5. In that dir: npm install (few minutes)

Step 2 — Token-Based Auth (one-time, in the Sandbox)

1. Create an Integration Record (Setup > Integration > Manage Integrations > New): - Name: Athos Theme Dev Tools - State: Enabled - ✅ Token-Based Authentication - ✅ TBA: Authorization Flow · Callback URL: http://localhost:7777/tba - ⬜ Authorization Code Grant (unchecked) - ✅ User Credentials
2. Save → copy Consumer Key + Secret
3. Paste into the .env file in the tools root dir - ⚠️ Never commit .env — add to .gitignore before any git init (standing rule).

Step 3 — Clone the active theme

gulp theme:fetch --account <SANDBOX_ACCT_ID>-sb1

(Sandbox account id looks like 4582045-sb1 — confirm the exact suffix in the Sandbox URL.) Pulls the active theme's Sass/HTML/templates into the Theme directory. This is what unblocks Claude writing the real override files — I need the base Facets.Browse.View.tpl, header search form, ProductDetails.Full.View.tpl, cart, and 404 templates.

Step 4 — Local dev loop

gulp theme:local

Compiles + starts a watching local server. Edit templates → see changes live.

Step 5 — Deploy to Sandbox + activate

gulp theme:deploy --account <SANDBOX_ACCT_ID>-sb1
gulp reactivate                      # or: gulp theme:deploy --reactivate

Then confirm the custom theme is applied to the Sandbox SC site.

After the theme is cloned — hand these back to Claude

1. The pulled templates (paths above) so I can write exact overrides from the build kit (athos-frontend-build-kit.md).
2. Answer the 3 binding checks (from the build kit §Binding risks): is the category External ID available in the SC category model? the PDP itemid template handle? the customer-id session handle?

Notes

• One theme per workspace. If we later also want prod, use a second root dir.
• Don't move/rename files inside the tools root dir.

Sources

• Set Up Theme Developer Tools (Oracle)
• Gulp Command Reference (Oracle)
• Fetch Active Theme (Oracle)