Merchant Center Custom Application, zero to nav

The headless run

The sequence

1. Start by asking the user for the form data, in chat, before running anything that touches their account. Ask the app name first: the other defaults derive from it. Then, as in Step 1 of the manual steps: node <skill-dir>/scripts/intake.mjs form --app-name <name> gives the batches, intake.mjs check --answers <file> validates the answers. Hosting is whatever the user already uses; Vercel, Netlify, Cloudflare Pages and Connect have deployment help.

2. Sign in and list the install targets. Run the script with the form's answers and no plan:

   node <skill-dir>/scripts/headless.mjs --app-name <name> --region <region> --project-key <key> \
     --entry-point <path> --menu-label <label> --contact-email <email> --app-dir <dir> \
     --template <starter-typescript|starter> --hosting <provider> [--deploy-help on|off]
   
   It checks the tools and the session. With no valid session it starts the login, prints [session] https://... on stderr and waits for the credentials file: give the user that URL and let the run wait. Then it exits 4 with needs.ctx set to installPlan and needs.options, the Organizations the user administers with their projects.
3. Ask the user where to install: which Organizations, and all projects or an allowlist for each. Write the plan file, a JSON array with one entry per Organization: orgId, orgName, allProjects (true or false), projectKeys (empty when allProjects is true, at least one key otherwise).
4. Get the review: the same command plus --install-plan <file>. Exit 0 with stage: "review". Show review to the user in full: the app (name, entry point, region, folder, template, project key, menu label), contact email, hosting, the plan, the owner Organization, deployment help. When the plan names several Organizations and no --org-id was given, it exits 4 with needs.ctx set to orgId and the options: ask, rerun with --org-id <id>. Nothing in the account has changed yet.
5. Get an explicit yes to that review. Then the same command plus --confirmed. It creates the app, runs git init -b main in the app folder (the repository root with Connect; init only, no commit or remote), builds, registers, deploys, checks the host, finishes registration, and ends with productionUrl and opened.
6. Act on the exit code (table below). A need is answered with --set <field>=<value>, or the named environment variable for a secret, and the same command again.
7. Finish as in Step 7 of the manual steps: opened is the Merchant Center URL of the app inside a Project. Open it, or hand it to the user, and confirm the menu item. Do not report success from exit 0 alone.

Exit codes

What a step may need

Cloudflare Pages

• Production URL: https://<project>.pages.dev, or a custom domain attached to the project. The project domain is stable; every deploy also gets a hashed https://<hash>.<project>.pages.dev URL, which is never used.
• Build: pnpm build, output in public.
• Rewrite: none to write. Without a 404.html in the output, Pages serves the root for every path that is not a static asset, which is the single-page behaviour the Merchant Center proxy needs. The host check proves it on the deeper path.
• Deploy: wrangler pages deploy public --project-name <project> --branch main --commit-dirty=true, to the production branch.
• Env vars: only when the config uses ${env:...} placeholders. The build runs locally here and the upload is direct, so set them in the shell or a dotenv file before pnpm build. The Pages project's environment variables only apply to builds Cloudflare runs from Git.

What the session runs with deployment help on

1. wrangler whoami --json. Not signed in: the session asks for an API token with Pages edit rights, carried as CLOUDFLARE_API_TOKEN in the environment, or the user runs wrangler login in another terminal and presses Enter. With several accounts the user picks one; its id travels as CLOUDFLARE_ACCOUNT_ID, because Wrangler refuses to choose without a terminal.
2. wrangler pages project list --json. The project named after the app folder is reused, with its .pages.dev domain as the production URL. Otherwise wrangler pages project create <name> --production-branch main, and the URL is read from the "It will be available at" line. A name Cloudflare refuses is asked for again.
3. Patches the config with the project URL, builds, deploys. One deploy is enough: the domain is known before the build.
4. A redirect to a Cloudflare Access login page, or a 401/403, means Cloudflare Access covers the domain; the host check fails at once and says where to remove the Access application.

commercetools Connect

What is different from a static host

• Layout. The folder named in the form is the repository root. It holds connect.yaml and the app one level down, in a folder named like the deployAs entry (the app folder name). Connect requires that match. A resume may name either level.
• Package manager. Connect builds Node projects with npm or yarn only, so the app is scaffolded with --package-manager npm and built locally with npm run build. The pnpm build-script step does not apply.
• URL. Connect provides APPLICATION_URL at build time, so the config holds url: '${env:APPLICATION_URL}' instead of a literal. The local build sets a placeholder for it; register.mjs sets it to the real URL when it syncs. The literal never needs to be committed.
• Identity. connect.yaml declares CUSTOM_APPLICATION_ID, ENTRY_POINT_URI_PATH and CLOUD_IDENTIFIER; the session passes the registered applicationId, the entry point and the cloud identifier as the Deployment's configuration. That is why registration (Draft, which yields the id) comes before the deploy, as on every host.
• Repository. Connect fetches a public repository over HTTPS. A private one needs the SSH URL and read access for the connect-mu machine user; the session grants it as a collaborator through gh api. If that invitation is still pending when Connect fetches, the publish report fails at its "Fetch Connector repository" step: accept the invitation for connect-mu (or make the repository public) and press r.
• Deployment type. The session creates a sandbox Deployment: it needs no production Project and is the type Connect deploys by default. A production Deployment is a later, separate decision: it needs a non-trial Project, and before the first one the user contacts their Customer Success Manager or commercetools support.

connect.yaml

deployAs:
  - name: <app folder>
    applicationType: merchant-center-custom-application
    configuration:
      standardConfiguration:
        - key: CUSTOM_APPLICATION_ID
          description: The Custom Application ID
          required: true
        - key: ENTRY_POINT_URI_PATH
          description: The Application entry point URI path
          required: true
        - key: CLOUD_IDENTIFIER
          description: The cloud identifier
          default: '<cloud identifier>'

What the session runs with deployment help on

1. API client. Connect needs an API client for the Project with the scopes manage_connectors and manage_connectors_deployments. The session asks for its id, then its secret (kept in memory, never logged). A rejected secret is asked for again.
2. Repository and tag. git init -b main if needed, git add -A, a commit, gh auth status (the GitHub CLI must be signed in), and if there is no origin, the user picks public or private and the session runs gh repo create <name> --<visibility> --source <root> --remote origin --push. Then a new tag v0.1.<n> is made and pushed. Every run makes a new tag, because Connect builds a tag, not a branch.
3. Connector. A ConnectorStaged keyed after the app folder is created with the repository and tag, the region, and the Project in privateProjects, or repointed at the new tag with setRepository. It is published for private use (certification: false). The step polls every 15 seconds until the status is Published; Failed stops with the publishing report.
4. Deployment. A sandbox Deployment keyed <name>-sandbox is created with the configuration above, or redeployed with updateConnector after a republish. The step polls until Deployed (up to 15 minutes) and takes applications[0].url as the production URL; Failed stops with the report.
5. The host check and the finish step then run as for any host.

When a publish fails on a fresh starter

Netlify

• Production URL: https://<site>.netlify.app, or a custom domain. The site name is known once the site exists, so the site is created or linked first. The CLI renames a site when the name is taken (a numeric suffix), so the URL is read from its output, never assumed.
• Build: pnpm build (the starter's build script is mc-scripts build), publish directory public.
• Rewrite: netlify.toml in the project root:

  [build]
    command = "pnpm build"
    publish = "public"
  
  [[redirects]]
    from = "/*"
    to = "/index.html"
    status = 200
  
  The status = 200 is what makes it a rewrite and not a redirect.
• Deploy: netlify deploy --prod --no-build --dir public --site <name> --json after building. The url key of the JSON is the production URL; deploy_url is the per-deploy one and is never used.
• Env vars: only when the config uses ${env:...} placeholders. The build runs locally here and the deploy uploads it as is, so set them in the shell or a dotenv file before pnpm build. The site's build environment settings only apply to builds Netlify runs itself.

What the session runs with deployment help on

1. netlify status --json. Not signed in: the session asks for a personal access token, carried as NETLIFY_AUTH_TOKEN in the environment (never on the command line), or the user runs netlify login in another terminal and presses Enter.
2. Linked site (linked: true): its site-name and site-url are used. Otherwise netlify teams:list --json; with several teams the user picks one (the CLI would take the default by itself, which is exactly what must not happen), then netlify sites:create --name <app folder> --account-slug <team> --json.
3. Writes netlify.toml, patches the config with the site URL, builds, deploys. If the deploy lands on a different URL than planned, the config is patched to that URL and deployed once more.
4. A 401 or 403 from the host is Netlify site protection (a password or visitor access control); the host check fails at once and says where to turn it off.

Hosting contract (any provider)

A host qualifies if it meets these three requirements. The other files in this folder are how one provider meets them.

1. A stable https URL, known before the build. env.production.url feeds the compiled Content-Security-Policy, so the URL must be in the config before mc-scripts build runs. Use the production domain or a custom domain, never a per-deployment URL that changes on every build. If the host only reveals the URL after the first deploy, create or reserve the site first (most CLIs have a create or link command) and read the URL from it.
2. A rewrite of every path to index.html with status 200. A custom app is a single-page app and the Merchant Center proxy forwards /:projectKey/:entryPointUriPath/* to the host. A redirect is not a rewrite: the proxy does not follow it.
3. The public/ directory as the published output, produced by mc-scripts build (pnpm build in the starter). mc-scripts build also compiles index.html.

Procedure

1. Get the production URL (requirement 1).
2. node <skill-dir>/scripts/patch-config.mjs --app-dir <dir> --url <url>
3. Add the provider's rewrite rule (requirement 2) to the repo, so it is code and not a dashboard setting.
4. Build. Then show the user the deploy command and get their explicit confirmation before running it: it publishes the app. Deploy with the provider's tooling or Git integration.
5. node <skill-dir>/scripts/verify.mjs with the flags in Step 7 of the manual steps, and read hostCheck.problems. It tests the app path and a deeper path, so it catches a missing rewrite on any host.
6. Pass the URL to register.mjs --production-url.

Providers with a file here

Surge

• Production URL: you choose it: https://<project>.surge.sh. It is known before deploying, so requirement 1 of other.md needs no create or reserve step.
• Build: as in other.md, output in public.
• Rewrite: Surge serves 200.html for unknown paths. Copy the built file rather than renaming it as the guide does, so index.html still serves the root: cp public/index.html public/200.html. Re-copy after every build.
• Deploy: surge public https://<project>.surge.sh

Deploy to Vercel

1. Build settings as code

{
  "framework": null,
  "buildCommand": "pnpm build",
  "outputDirectory": "public",
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

2. Link first, to learn the production URL

vercel link --yes

This creates the Vercel project without deploying.

• Several teams. Without a terminal the CLI refuses to pick ("Multiple teams found"). List them with vercel teams ls, let the user pick, and add --scope <team> to every Vercel command.
• Not signed in ("No existing credentials found"). Either vercel login in another terminal, or a token from the Vercel account settings passed as --token.
• Production domain. https://<project-name>.vercel.app, where the name is what the CLI reports for the linked project (.vercel/project.json, or vercel project inspect). When the name is taken in another team, Vercel appends a suffix (<name>-pi.vercel.app), so the Aliased line of the deploy output is the source of truth. Never use the https://<project>-<hash>-<team>.vercel.app deployment URL: it changes on every deploy.
• Deployment Protection. In its default (Standard) mode it covers deployment URLs and previews, not the production domain. If the production domain answers 401 or 403, protection covers all deployments and must be turned off in the project settings, or the Merchant Center proxy cannot reach the app.

3. Write the URL into the config, build locally, deploy that build

node <skill-dir>/scripts/patch-config.mjs --app-dir . --url https://<project-name>.vercel.app
vercel pull --yes --environment production
vercel build --prod
vercel deploy --prebuilt --prod

4. Check the host

5. Hand back to register.mjs

What the session runs with deployment help on

Manual steps

Step 1: gather inputs (manual)

Walk the user through the form one batch at a time:

node scripts/intake.mjs form --app-name <name> [--hosting <provider>] [--email <email>]

node scripts/intake.mjs check --answers <file>

Step 2: preflight

node scripts/preflight.mjs --region <region> --entry-point <path> --hosting <provider>

Step 3: scaffold

This downloads and runs a package and then installs dependencies. Show the command and get the user's explicit yes before running it (on the session path, the review screen is that yes).

npx @commercetools-frontend/create-mc-app@latest <app-dir> --template starter-typescript \
  --entry-point-uri-path <path> --initial-project-key <project-key> \
  --cloud-identifier <region> --package-manager pnpm --yes

node scripts/allow-builds.mjs --app-dir <app-dir>

git init -b main
echo '.mc-onboarding/' >> .gitignore

The second line keeps the onboarding session log out of the repository.

Step 4: choose install targets, then register (first pass, no URL yet)

Choose where the app gets installed. This is a terminal picker, not a model task, and it needs the Merchant Center session from Step 2:

node scripts/install-plan.mjs --region <region> --out <app-dir>/install-plan.json

node scripts/register.mjs --app-dir <app-dir> --install-plan <app-dir>/install-plan.json --contact-email <email>

This is the first command that changes the user's account (it sets the Organization's contact and creates the app in Draft), so show it with the plan it will apply and get the user's explicit confirmation first; the session's review screen is that confirmation on the session path. Do the same before every run of Step 6, which also changes the account (URL, Ready, installs), and say so when the plan would remove an installed project.

Step 5: deploy

Step 6: finish registration

node scripts/register.mjs --app-dir <app-dir> --install-plan <app-dir>/install-plan.json --production-url <url>

Step 7: verify in the deployed project

node scripts/verify.mjs --production-url <url> --project-key <key> --entry-point <path> --region <region>

• With a browser automation tool, navigate to openInBrowser. If the page lands on the login screen, ask the user to sign in in that window, then continue. Take a snapshot and confirm two things: the menu item (the menu label) is in the main nav, and the app content renders. Report what the snapshot showed.
• If browser automation is not available, give the user the openInBrowser URL, ask them to open it and confirm the menu item, and say plainly that you did not see the nav.