create-solvapay 0.7.2 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-solvapay",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Scaffold SolvaPay-monetized projects — MCP servers on Cloudflare Workers and more.",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "node": ">=18.17"
   },
   "dependencies": {
-    "@solvapay/init": "^0.4.5"
+    "@solvapay/init": "^0.4.6"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/scripts/mcp/lib/openapi.mjs

@@ -15,12 +15,14 @@
  *   - buildAdvisories(operations, schemes) -> Advisory[]
  *   - buildSpecShapeAdvisories({ servers, operations, schemes }) -> Advisory[]
  *
- * The only non-stdlib dependency is `@apidevtools/swagger-parser`,
- * pulled on demand via `npx --package @apidevtools/swagger-parser`.
+ * Non-stdlib dependencies live in `scripts/mcp/package.json`
+ * (`@apidevtools/swagger-parser`, `js-yaml`).
  */
 
-import { access } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { access, readFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import yaml from 'js-yaml'
 
 const SUPPORTED_AUTH_KINDS = new Set([
   'http-bearer',
@@ -31,6 +33,16 @@ const SUPPORTED_AUTH_KINDS = new Set([
 
 const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE'])
 
+const OPENAPI_31_PATCH = /^3\.1\.\d+$/
+
+export function swaggerParserInstallHint() {
+  const scriptsDir = dirname(dirname(fileURLToPath(import.meta.url)))
+  return (
+    '`@apidevtools/swagger-parser` is not installed. Run `npm install` inside ' +
+    `${scriptsDir} (one-time setup), then re-run.`
+  )
+}
+
 /**
  * Load + parse an OpenAPI document and run `$ref` resolution through
  * swagger-parser's `dereference`. Accepts a local JSON/YAML path or an
@@ -41,10 +53,20 @@ const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE'])
  */
 export async function loadSpec(specPath) {
   const SwaggerParser = await loadSwaggerParser()
+  const document = normaliseOpenApiPatch(await readSpecDocument(specPath))
+  try {
+    const spec = await SwaggerParser.dereference(document)
+    return { spec }
+  } catch (err) {
+    throw wrapSpecLoadError(err, specPath)
+  }
+}
+
+async function readSpecDocument(specPath) {
   if (/^https?:\/\//i.test(specPath)) {
+    let response
     try {
-      const spec = await SwaggerParser.dereference(specPath)
-      return { spec }
+      response = await fetch(specPath)
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err)
       throw new Error(
@@ -52,6 +74,13 @@ export async function loadSpec(specPath) {
           'Point at the raw JSON/YAML document (e.g. .../swagger.json or .../openapi.yaml), not a docs/Swagger UI page.',
       )
     }
+    if (!response.ok) {
+      throw new Error(
+        `Could not load OpenAPI spec from ${specPath}: HTTP ${response.status}. ` +
+          'Point at the raw JSON/YAML document (e.g. .../swagger.json or .../openapi.yaml), not a docs/Swagger UI page.',
+      )
+    }
+    return parseSpecText(await response.text(), specPath)
   }
 
   const absolute = resolve(specPath)
@@ -63,16 +92,63 @@ export async function loadSpec(specPath) {
     }
     throw err
   }
-  const spec = await SwaggerParser.dereference(absolute)
-  return { spec }
+  return parseSpecText(await readFile(absolute, 'utf8'), absolute)
+}
+
+function parseSpecText(text, source) {
+  const trimmed = text.trim()
+  try {
+    if (trimmed.startsWith('{')) return JSON.parse(text)
+    const document = yaml.load(text)
+    if (!document || typeof document !== 'object' || Array.isArray(document)) {
+      throw new Error('document is not an object')
+    }
+    return document
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    throw new Error(
+      `Could not load OpenAPI spec from ${source}: ${message}. ` +
+        'Point at the raw JSON/YAML document (e.g. .../swagger.json or .../openapi.yaml), not a docs/Swagger UI page.',
+    )
+  }
+}
+
+function normaliseOpenApiPatch(spec) {
+  if (
+    typeof spec?.openapi === 'string' &&
+    OPENAPI_31_PATCH.test(spec.openapi) &&
+    spec.openapi !== '3.1.0' &&
+    spec.openapi !== '3.1.1'
+  ) {
+    console.log('OpenAPI 3.1.x patch version normalised to 3.1.1 for parsing.')
+    spec.openapi = '3.1.1'
+  }
+  return spec
+}
+
+function wrapSpecLoadError(err, specPath) {
+  const message = err instanceof Error ? err.message : String(err)
+  if (message.includes('Unsupported OpenAPI version')) {
+    return new Error(
+      `Could not parse OpenAPI spec from ${specPath}: ${message} ` +
+        'OpenAPI 3.1.x patch versions are rewritten to 3.1.1 before parsing. ' +
+        'For any other unsupported version, set the openapi field to 3.1.1 in a local copy of the spec.',
+    )
+  }
+  if (/^https?:\/\//i.test(specPath)) {
+    return new Error(
+      `Could not load OpenAPI spec from ${specPath}: ${message}. ` +
+        'Point at the raw JSON/YAML document (e.g. .../swagger.json or .../openapi.yaml), not a docs/Swagger UI page.',
+    )
+  }
+  return err instanceof Error ? err : new Error(message)
 }
 
 /**
- * Lazy-load `@apidevtools/swagger-parser`. The skill ships a tiny
- * `scripts/package.json` declaring this single dep; the user runs
- * `npm install` inside `scripts/` once per checkout before invoking
- * `describe.mjs`, `scaffold.mjs`, or `test.mjs`. The error message
- * here exists for the case where someone skipped that step.
+ * Lazy-load `@apidevtools/swagger-parser`. `scripts/mcp/package.json`
+ * declares it; the user runs `npm install` inside `scripts/mcp` once
+ * before invoking `describe.mjs`, `scaffold.mjs`, or `test.mjs`. The
+ * error message here exists for the case where someone skipped that step.
  */
 async function loadSwaggerParser() {
   try {
@@ -80,10 +156,7 @@ async function loadSwaggerParser() {
     return mod.default ?? mod
   } catch (err) {
     if (err && typeof err === 'object' && err.code === 'ERR_MODULE_NOT_FOUND') {
-      throw new Error(
-        '`@apidevtools/swagger-parser` is not installed. Run `npm install` inside the ' +
-          '`scripts/` directory of this skill (one-time setup), then re-run.',
-      )
+      throw new Error(swaggerParserInstallHint())
     }
     throw err
   }

package/scripts/mcp/lib/openapi.test.mjs

@@ -0,0 +1,63 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { loadSpec, swaggerParserInstallHint } from './openapi.mjs'
+
+const tempDirs = []
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+})
+
+function writeSpec(document) {
+  const dir = mkdtempSync(join(tmpdir(), 'openapi-spec-'))
+  tempDirs.push(dir)
+  const specPath = join(dir, 'openapi.json')
+  writeFileSync(specPath, JSON.stringify(document))
+  return specPath
+}
+
+const minimalSpec = version => ({
+  openapi: version,
+  info: { title: 'trial', version: '1.0.0' },
+  paths: {},
+})
+
+describe('loadSpec OpenAPI version', () => {
+  it('normalises an OpenAPI 3.1.x patch version to 3.1.1 before parsing', async () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const specPath = writeSpec(minimalSpec('3.1.2'))
+
+    const { spec } = await loadSpec(specPath)
+
+    expect(spec.openapi).toBe('3.1.1')
+    expect(log).toHaveBeenCalledWith('OpenAPI 3.1.x patch version normalised to 3.1.1 for parsing.')
+  })
+
+  it('leaves OpenAPI 3.1.1 unchanged and does not print the normalisation line', async () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const specPath = writeSpec(minimalSpec('3.1.1'))
+
+    const { spec } = await loadSpec(specPath)
+
+    expect(spec.openapi).toBe('3.1.1')
+    expect(log).not.toHaveBeenCalledWith(
+      'OpenAPI 3.1.x patch version normalised to 3.1.1 for parsing.',
+    )
+  })
+
+  it('wraps an unsupported OpenAPI version in a readable error', async () => {
+    const specPath = writeSpec(minimalSpec('3.2.0'))
+
+    await expect(loadSpec(specPath)).rejects.toThrow(/Could not parse OpenAPI spec/)
+    await expect(loadSpec(specPath)).rejects.toThrow(/Unsupported OpenAPI version: 3.2.0/)
+  })
+})
+
+describe('swaggerParserInstallHint', () => {
+  it('names the scripts/mcp directory that owns the swagger-parser dependency', () => {
+    expect(swaggerParserInstallHint()).toMatch(/Run `npm install` inside .+\/scripts\/mcp\b/)
+  })
+})

package/scripts/mcp/package-lock.json

@@ -8,7 +8,8 @@
       "name": "@solvapay-skills/create-solvapay-mcp",
       "version": "0.0.0",
       "dependencies": {
-        "@apidevtools/swagger-parser": "^10.1.0"
+        "@apidevtools/swagger-parser": "^10.1.0",
+        "js-yaml": "^4.3.2"
       }
     },
     "node_modules/@apidevtools/json-schema-ref-parser": {
@@ -138,9 +139,19 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/js-yaml": {
-      "version": "4.1.1",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
-      "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.2.tgz",
+      "integrity": "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/nodeca"
+        }
+      ],
       "license": "MIT",
       "dependencies": {
         "argparse": "^2.0.1"

package/scripts/mcp/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "description": "Internal runtime deps for create-solvapay MCP scripts. Run `npm install` once inside this directory before invoking describe.mjs / scaffold.mjs / test.mjs.",
   "dependencies": {
-    "@apidevtools/swagger-parser": "^10.1.0"
+    "@apidevtools/swagger-parser": "^10.1.0",
+    "js-yaml": "^4.3.2"
   }
 }

package/scripts/mcp/scaffold.mjs

@@ -27,6 +27,7 @@
  *   }
  */
 
+import { spawnSync } from 'node:child_process'
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { resolve, dirname, relative, isAbsolute, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -146,6 +147,7 @@ async function main() {
   await writeIndexFile(target, toolFiles, selections.upstreamAuth.kind, mode)
   await ensureGitignoreCoversEnv(target)
   const envWritten = await writeDotEnv(target, selections)
+  installGeneratedScriptDeps(target)
 
   const planReminders = Array.isArray(selections.plans)
     ? collectPlanSelectionReminders(selections.plans)
@@ -157,12 +159,12 @@ async function main() {
     ...(mode === 'intent-driven'
       ? [
           'Intent-driven mode: author src/tools/*.ts files per intent-driven.md, then update src/tools/index.ts to import and call each register{IntentName}(ctx, env). The .env and project skeleton are ready.',
-          `Run \`npx solvapay init\` inside ${target} to populate SOLVAPAY_SECRET_KEY (see the generated README).`,
+          `Run \`npx -y solvapay@latest init\` inside ${target} to populate SOLVAPAY_SECRET_KEY (see the generated README).`,
           `\`node scripts/verify.mjs <url>\` runs from ${target} with no extra setup. \`node scripts/test.mjs\` will report intent tools as skipped (they aren't in the spec's operationIds) — exercise them manually per intent-driven.md.`,
         ]
       : [
-          `Run \`npx solvapay init\` inside ${target} to populate SOLVAPAY_SECRET_KEY (see the generated README).`,
-          `\`node scripts/verify.mjs <url>\` runs from ${target} with no extra setup. Before \`node scripts/test.mjs\`, run \`( cd scripts && npm install )\` once inside ${target}.`,
+          `Run \`npx -y solvapay@latest init\` inside ${target} to populate SOLVAPAY_SECRET_KEY (see the generated README).`,
+          `\`node scripts/verify.mjs <url>\` and \`node scripts/test.mjs\` run from ${target}. Scaffold already ran \`npm install\` inside ${target}/scripts.`,
         ]),
   ]
 
@@ -974,7 +976,7 @@ async function writeDotEnv(target, selections) {
       : PLACEHOLDERS.PRODUCT_REF
   const lines = [
     '# Generated by create-solvapay scaffold.',
-    '# SOLVAPAY_SECRET_KEY is populated by `npx solvapay init` (see the generated README).',
+    '# SOLVAPAY_SECRET_KEY is populated by `npx -y solvapay@latest init` (see the generated README).',
     `SOLVAPAY_PRODUCT_REF=${productRef}`,
     `MCP_PUBLIC_BASE_URL=${selections.mcpPublicBaseUrl}`,
   ]
@@ -1032,7 +1034,20 @@ function collectWrittenPaths(target, toolFiles, envPath) {
   for (const id of toolFiles) {
     written.push(join(target, 'src', 'tools', `${id}.ts`))
   }
-  return written.map(p => relative(process.cwd(), p))
+  return written.map(p => resolve(p))
+}
+
+function installGeneratedScriptDeps(target) {
+  const scriptsDir = join(target, 'scripts')
+  const result = spawnSync('npm', ['install', '--no-audit', '--no-fund'], {
+    cwd: scriptsDir,
+    encoding: 'utf8',
+  })
+  if ((result.status ?? 1) !== 0) {
+    const detail = [result.stdout, result.stderr].filter(Boolean).join('\n')
+    console.error(`npm install inside ${scriptsDir} failed.\n${detail}`)
+    process.exit(result.status ?? 1)
+  }
 }
 
 function jsKey(name) {

package/templates/mcp/_base/.env.example

@@ -12,7 +12,7 @@
 # The SolvaPay secret key for your merchant account. Never commit.
 # Populated by `npx solvapay init`. Uploaded to Cloudflare as a Worker
 # Secret automatically on the first `npm run deploy`.
-SOLVAPAY_SECRET_KEY=sk_test_your_key_here
+SOLVAPAY_SECRET_KEY=sk_sandbox_your_key_here
 
 # Product ref the paywall gates on. Create one in the SolvaPay Console
 # under Products and copy its `prd_…` ID. Populated by scaffold.

package/templates/mcp/_base/README.md

@@ -96,7 +96,7 @@ npm run verify -- http://localhost:8787 --credentials-file ./credentials.json
 `.env` (gitignored) is what `wrangler dev` reads:
 
 ```
-SOLVAPAY_SECRET_KEY=sk_test_…       # populated by `npx solvapay init`
+SOLVAPAY_SECRET_KEY=sk_sandbox_…    # populated by `npx -y solvapay@latest init`
 SOLVAPAY_PRODUCT_REF=__SOLVAPAY_PRODUCT_REF__
 MCP_PUBLIC_BASE_URL=__MCP_PUBLIC_BASE_URL__
 UPSTREAM_API_KEY=…                  # bearer or single apiKey-header upstream auth
@@ -139,7 +139,7 @@ Then redeploy.
 ## Go-live (swap sandbox → live)
 
 1. Generate a live key in the SolvaPay Console (API Keys → Live).
-2. Replace `SOLVAPAY_SECRET_KEY=sk_test_…` with `SOLVAPAY_SECRET_KEY=sk_live_…` in `.env`.
+2. Replace `SOLVAPAY_SECRET_KEY=sk_sandbox_…` with `SOLVAPAY_SECRET_KEY=sk_live_…` in `.env`.
 3. The first-deploy auto-upload only runs when no `SOLVAPAY_SECRET_KEY` is present on the worker. Since one is already there, push the new value explicitly: `npx wrangler secret put SOLVAPAY_SECRET_KEY`.
 4. `npm run deploy`.
 

package/templates/mcp/_base/package.json

@@ -7,7 +7,6 @@
     "build": "cross-env INPUT=mcp-app.html vite build && mkdir -p src/assets && cp dist/mcp-app.html src/assets/mcp-app.html",
     "dev": "npm run build && node scripts/dev.mjs",
     "dev:widget": "cross-env INPUT=mcp-app.html vite build --watch",
-    "predeploy": "npm run build",
     "deploy": "node scripts/deploy.mjs",
     "serve:local": "wrangler dev",
     "typecheck": "tsc --noEmit",

package/templates/mcp/_base/scripts/deploy.mjs

@@ -103,7 +103,10 @@ function listWorkerSecretNames() {
 }
 
 function putWorkerSecret(name, value) {
-  const result = runWrangler(['secret', 'put', name], { input: value })
+  const workerName = readWranglerConfig().name
+  const args = ['secret', 'put', name]
+  if (workerName && !workerName.includes('__')) args.push('--name', workerName)
+  const result = runWrangler(args, { input: value })
   if (result.status !== 0) process.exit(result.status ?? 1)
 }
 
@@ -119,7 +122,7 @@ function getWranglerWhoami() {
   }
 }
 
-function wranglerConfigPaths() {
+export function wranglerConfigPaths() {
   const home = homedir()
   const paths = []
 
@@ -127,21 +130,29 @@ function wranglerConfigPaths() {
     paths.push(join(process.env.WRANGLER_HOME, 'config', 'default.toml'))
   }
 
+  if (process.env.XDG_CONFIG_HOME) {
+    paths.push(join(process.env.XDG_CONFIG_HOME, '.wrangler', 'config', 'default.toml'))
+  }
+
   paths.push(join(home, 'Library', 'Preferences', '.wrangler', 'config', 'default.toml'))
   paths.push(join(home, '.wrangler', 'config', 'default.toml'))
 
   return paths
 }
 
-function readWranglerOAuthToken() {
-  for (const path of wranglerConfigPaths()) {
+export function readOAuthTokenFromConfigPaths(paths) {
+  for (const path of paths) {
     if (!existsSync(path)) continue
     const match = readFileSync(path, 'utf8').match(/^oauth_token\s*=\s*"([^"]+)"/m)
-    if (match?.[1]) return match[1]
+    return match?.[1] ?? null
   }
   return null
 }
 
+function readWranglerOAuthToken() {
+  return readOAuthTokenFromConfigPaths(wranglerConfigPaths())
+}
+
 function resolveCloudflareApiToken() {
   const fromEnv = process.env.CLOUDFLARE_API_TOKEN?.trim()
   if (fromEnv) return fromEnv
@@ -313,9 +324,10 @@ function failSubdomainNotRegistered(accountId) {
     [
       '',
       'This Cloudflare account has not registered a workers.dev subdomain yet.',
-      'Register one (one-time setup), then re-run `npm run deploy`:',
+      `Account ${accountId}: opening Workers & Pages creates the workers.dev subdomain; no paid plan needed.`,
+      'Do that once, then re-run `npm run deploy`:',
       '',
-      `  https://dash.cloudflare.com/${accountId}/workers/onboarding`,
+      '  https://dash.cloudflare.com/?to=/:account/workers-and-pages',
       '',
     ].join('\n'),
   )
@@ -843,72 +855,100 @@ function parseDotEnv(contents) {
   return env
 }
 
-const localEnv = existsSync(dotEnvPath) ? parseDotEnv(readFileSync(dotEnvPath, 'utf8')) : {}
+function uploadWorkerSecrets(localEnv, { dryRun, force }) {
+  ensureSolvaPaySecretKey(localEnv, { dryRun })
+  ensureUpstreamApiKeySecret(localEnv, { dryRun, force })
+  ensureUpstreamOAuthSecrets(localEnv, { dryRun })
+  ensureUpstreamApiHeadersSecret(localEnv, { dryRun, force })
+}
 
-if (!existsSync(dotEnvPath)) {
-  console.error(
-    [
-      '',
-      `⚠  ${dotEnvPath} not found — deploying with placeholder vars from wrangler.jsonc.`,
-      '   Run `npx solvapay init` (which writes SOLVAPAY_SECRET_KEY) and verify the other',
-      '   keys in .env match your merchant, then re-run `npm run deploy` — it uploads',
-      '   SOLVAPAY_SECRET_KEY from .env as a Worker secret on the first deploy.',
-      '',
-    ].join('\n'),
-  )
+function runProjectBuild() {
+  const result = spawnSync('npm', ['run', 'build'], { cwd: projectRoot, stdio: 'inherit' })
+  if ((result.status ?? 1) !== 0) process.exit(result.status ?? 1)
 }
 
-const dryRun = passthrough.includes('--dry-run')
-const yesFlag =
-  passthrough.includes('--yes') ||
-  passthrough.includes('-y') ||
-  process.env.SOLVAPAY_DEPLOY_YES === '1'
-const forceFlag = passthrough.includes('--force')
+async function main() {
+  const localEnv = existsSync(dotEnvPath) ? parseDotEnv(readFileSync(dotEnvPath, 'utf8')) : {}
 
-const preflight = await runDeployPreflight({ dryRun })
-const resolvedPublicUrl = ensureMcpPublicBaseUrl(localEnv, preflight, { dryRun })
+  if (!existsSync(dotEnvPath)) {
+    console.error(
+      [
+        '',
+        `⚠  ${dotEnvPath} not found — deploying with placeholder vars from wrangler.jsonc.`,
+        '   Run `npx -y solvapay@latest init` (which writes SOLVAPAY_SECRET_KEY) and verify the other',
+        '   keys in .env match your merchant, then re-run `npm run deploy` — it uploads',
+        '   SOLVAPAY_SECRET_KEY from .env as a Worker secret on the first deploy.',
+        '',
+      ].join('\n'),
+    )
+  }
 
-const confirmation = await confirmDeploymentUrl(localEnv, preflight, { dryRun, yes: yesFlag })
-if (confirmation === 'abort') process.exit(1)
+  const dryRun = passthrough.includes('--dry-run')
+  const yesFlag =
+    passthrough.includes('--yes') ||
+    passthrough.includes('-y') ||
+    process.env.SOLVAPAY_DEPLOY_YES === '1'
+  const forceFlag = passthrough.includes('--force')
+
+  const preflight = await runDeployPreflight({ dryRun })
+  runProjectBuild()
+  const resolvedPublicUrl = ensureMcpPublicBaseUrl(localEnv, preflight, { dryRun })
+
+  const confirmation = await confirmDeploymentUrl(localEnv, preflight, { dryRun, yes: yesFlag })
+  if (confirmation === 'abort') process.exit(1)
+
+  // Verify the merchant exists on the SolvaPay backend before uploading
+  // the secret key. Otherwise a 404-from-the-backend deploy looks like a
+  // success at the `wrangler deploy` level but every paid tool fails at
+  // runtime.
+  await runSolvaPayPreflight({
+    secretKey: localEnv.SOLVAPAY_SECRET_KEY?.trim(),
+    apiBaseUrl: localEnv.SOLVAPAY_API_BASE_URL?.trim(),
+    dryRun,
+  })
 
-// Verify the merchant exists on the SolvaPay backend before uploading
-// the secret key. Otherwise a 404-from-the-backend deploy looks like a
-// success at the `wrangler deploy` level but every paid tool fails at
-// runtime.
-await runSolvaPayPreflight({
-  secretKey: localEnv.SOLVAPAY_SECRET_KEY?.trim(),
-  apiBaseUrl: localEnv.SOLVAPAY_API_BASE_URL?.trim(),
-  dryRun,
-})
+  // `wrangler secret put` on a worker that does not exist yet prompts to
+  // create one. Upload only after the first successful deploy in that case.
+  const workerExistedBeforeDeploy = listWorkerSecretNames() !== null
+  if (workerExistedBeforeDeploy) {
+    uploadWorkerSecrets(localEnv, { dryRun, force: forceFlag })
+  }
 
-ensureSolvaPaySecretKey(localEnv, { dryRun })
-ensureUpstreamApiKeySecret(localEnv, { dryRun, force: forceFlag })
-ensureUpstreamOAuthSecrets(localEnv, { dryRun })
-ensureUpstreamApiHeadersSecret(localEnv, { dryRun, force: forceFlag })
+  const wranglerPassthrough = passthrough.filter(
+    arg => arg !== '--yes' && arg !== '-y' && arg !== '--force',
+  )
+  const wranglerArgs = ['deploy']
+  for (const name of OVERRIDABLE_VARS) {
+    const value = localEnv[name]
+    if (value) wranglerArgs.push('--var', `${name}:${value}`)
+  }
+  wranglerArgs.push(...wranglerPassthrough)
 
-const wranglerPassthrough = passthrough.filter(
-  arg => arg !== '--yes' && arg !== '-y' && arg !== '--force',
-)
-const wranglerArgs = ['deploy']
-for (const name of OVERRIDABLE_VARS) {
-  const value = localEnv[name]
-  if (value) wranglerArgs.push('--var', `${name}:${value}`)
-}
-wranglerArgs.push(...wranglerPassthrough)
+  const result = runWrangler(wranglerArgs, { captureOutput: true })
+  printCapturedWranglerOutput(result)
 
-const result = runWrangler(wranglerArgs, { captureOutput: true })
-printCapturedWranglerOutput(result)
+  if ((result.status ?? 1) === 0 && !workerExistedBeforeDeploy) {
+    uploadWorkerSecrets(localEnv, { dryRun, force: forceFlag })
+  }
 
-if (resolvedPublicUrl && !dryRun) {
-  verifyDeployedWorkersDevUrl(resolvedPublicUrl, `${result.stdout ?? ''}\n${result.stderr ?? ''}`)
-}
+  if (resolvedPublicUrl && !dryRun) {
+    verifyDeployedWorkersDevUrl(resolvedPublicUrl, `${result.stdout ?? ''}\n${result.stderr ?? ''}`)
+  }
 
-if (!dryRun && (result.status ?? 1) === 0) {
-  const finalUrl = localEnv.MCP_PUBLIC_BASE_URL?.trim()
-  if (finalUrl) {
-    const { name } = readWranglerConfig()
-    printDeployedConnectionSnippets(finalUrl, name)
+  if (!dryRun && (result.status ?? 1) === 0) {
+    const finalUrl = localEnv.MCP_PUBLIC_BASE_URL?.trim()
+    if (finalUrl) {
+      const { name } = readWranglerConfig()
+      printDeployedConnectionSnippets(finalUrl, name)
+    }
   }
+
+  process.exit(result.status ?? 1)
 }
 
-process.exit(result.status ?? 1)
+const isDirectRun =
+  Boolean(process.argv[1]) && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+
+if (isDirectRun) {
+  await main()
+}

package/templates/mcp/_base/scripts/deploy.test.mjs

@@ -0,0 +1,55 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { readOAuthTokenFromConfigPaths, wranglerConfigPaths } from './deploy.mjs'
+
+describe('wranglerConfigPaths', () => {
+  const originalWranglerHome = process.env.WRANGLER_HOME
+  const originalXdg = process.env.XDG_CONFIG_HOME
+
+  afterEach(() => {
+    if (originalWranglerHome === undefined) delete process.env.WRANGLER_HOME
+    else process.env.WRANGLER_HOME = originalWranglerHome
+    if (originalXdg === undefined) delete process.env.XDG_CONFIG_HOME
+    else process.env.XDG_CONFIG_HOME = originalXdg
+  })
+
+  it('checks XDG_CONFIG_HOME after WRANGLER_HOME and before the macOS preferences path', () => {
+    process.env.WRANGLER_HOME = '/tmp/wrangler-home'
+    process.env.XDG_CONFIG_HOME = '/tmp/xdg-config'
+    const paths = wranglerConfigPaths()
+    expect(paths[0]).toBe('/tmp/wrangler-home/config/default.toml')
+    expect(paths[1]).toBe('/tmp/xdg-config/.wrangler/config/default.toml')
+    expect(paths[2]).toMatch(/Library\/Preferences\/\.wrangler\/config\/default\.toml$/)
+  })
+})
+
+describe('readOAuthTokenFromConfigPaths', () => {
+  const dirs = []
+
+  afterEach(() => {
+    for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+  })
+
+  function writeConfig(token) {
+    const dir = mkdtempSync(join(tmpdir(), 'wrangler-cfg-'))
+    dirs.push(dir)
+    mkdirSync(join(dir, 'config'), { recursive: true })
+    const path = join(dir, 'config', 'default.toml')
+    writeFileSync(path, token == null ? 'no_token = true\n' : `oauth_token = "${token}"\n`)
+    return path
+  }
+
+  it('stops at the first config file that exists, even when it has no token', () => {
+    const first = writeConfig(null)
+    const second = writeConfig('from-later-file')
+    expect(readOAuthTokenFromConfigPaths([first, second])).toBeNull()
+  })
+
+  it('reads the token from the first existing config file', () => {
+    const missing = join(tmpdir(), 'does-not-exist-wrangler-config.toml')
+    const found = writeConfig('from-xdg')
+    expect(readOAuthTokenFromConfigPaths([missing, found])).toBe('from-xdg')
+  })
+})