fix(create-app): design contracts for local Docker start failure and transient UVE 403 (#37262)

[fmontes]

PR 2 of 2 for #37262, stacked on #37263 (the spec).

The problem

npx @dotcms/create-app --local never starts dotCMS — it races Postgres and dies. Hand-starting corrupts the install, every UVE call 403s forever, and the CLI exits with nothing scaffolded.

flowchart TD
    A["dotcms starts before Postgres accepts connections"] -->|no restart policy| B["exits, stays dead"]
    B --> C["user hand-starts it from Docker Desktop"]
    C --> D["starter import left incomplete"]
    D --> E["every Apps API call 403s — permanently"]
    E --> F["CLI exits 1 · empty directory · working token discarded"]

    FIX1["**Fix 1** — compose gates dotcms on db + opensearch<br/>healthy, with a restart policy"]
    FIX2["**Fix 2** — UVE failure is non-fatal:<br/>project still scaffolds, .env still written"]

    FIX1 -.->|removes| A
    FIX2 -.->|removes| F

    style FIX1 fill:#dff0e8,stroke:#146046,color:#000
    style FIX2 fill:#dff0e8,stroke:#146046,color:#000
    style F fill:#fbe7e4,stroke:#a8281f,color:#000

Loading

The fix

One compose file, owned by the CLI. It ships inside the package instead of being fetched from main, so dotcms can be gated on db and opensearch reporting healthy, given restart: unless-stopped, and health-checked on /dotmgt/livez. The shared single-node-demo-site example is untouched. This alone removes the 403, because it removes the interrupted boot that causes it.

A failed UVE call no longer destroys the run. Two duplicated exit-on-failure call sites collapse into one configureUVE() that never calls process.exit. The 403 guidance differs by path: recreate the local stack, or check the token's permissions on your own server — opposite advice for the same status code.

Nothing successful is discarded. An exit handler writes .env and reports the connection details on every terminal path, including the 14 process.exit sites a finally cannot reach.

Recovery is unblocked. A dotCMS already on 8082 can be reused or replaced from the prompt instead of aborting; a failed npm install now actually reports failure; the compose file is never stranded in the parent directory.

The wait is legible. Compose progress is streamed with an elapsed-time ticker, and readiness moves to /dotmgt/readyz.

Verification

144 Jest tests. Two gates now run in CI via nx affected -t test: verify-compose-static (compose shape, no Docker) and verify-package (the asset is in dist/ and in npm pack output — asserting the artifact, not the manifests).

Verified end to end against a real stack: cold start healthy unaided in 60s, self-exit restarted by the policy, 8090 refused on the LAN address, and both 403 messages exercised against a stub.

One caveat. The spec's root cause 2 could not be independently reproduced: deleting the site's 27 permission rows still returned 200, because userDoesNotHaveAccess() short-circuits on user.isAdmin(). The fix is unaffected — it removes the crash, and the 403 handling is verified — but #37268 may be chasing the wrong data.

Checklist

• Tests — 144 Jest tests, written and confirmed failing before implementation (constitution Principle V). Cold-start behaviour is covered by verify-cold-start.sh; the full fault-injection E2E suite belongs to e2e: Add E2E test suite for @dotcms/create-app CLI #35096
• Translations — n/a
• Security Implications Contemplated — the management port is authorized by arrival port with no credential check, so it is bound to 127.0.0.1 rather than the wildcard, and a test asserts it is refused on the LAN address

Additional Info

No Java, no com.dotmarketing.*, no DB/ES/REST contract change — not rollback-unsafe. Per ADR-0019 this ships in a dotCMS release rather than a standalone SDK publish.

Refs #37262

This PR fixes: #37262

[claude]

Claude finished @fmontes's task in 5m 16s —— View job

---

Code Review — PR #37264

Reviewed the full diff. Findings below.

🆕 New Issues

🟠 withComposeFileMovedAside does not restore the compose file on the scaffolding-failure path it exists for — src/utils/compose-move.ts:30-36

The whole point of this helper (and AC-008) is the finally that moves docker-compose.yml back so a failed scaffold doesn't strand it in the parent directory. But the real scaffold-failure path doesn't throw — it calls process.exit(1):

// src/index.ts:784-787 (inside the action passed to withComposeFileMovedAside)
if (!created.ok) {
    spinner.fail(`Failed to scaffold frontend project (${selectedFramework}).`);
    process.exit(1);
}

process.exit() fires 'exit' handlers and terminates synchronously — it does not run finally blocks in suspended async functions. So on a clone/scaffold failure (the fresh-provision path, where the compose file was moved aside), the file is left in the parent directory and never restored — reintroducing exactly the AC-008 regression this module claims to prevent. cloneFrontEndSample errors are caught inside scaffoldFrontendProject and turned into Err, so this exit path is the normal one, not an edge case. Only a thrown error would let finally run.

🟡 Moving the compose file aside can clobber a pre-existing docker-compose.yml in the parent — src/utils/compose-move.ts:23,27

const asideNext = path.join(directory, '..', COMPOSE_FILE);
...
await fs.move(inProject, asideNext, { overwrite: true });

overwrite: true into the project's parent (typically the user's cwd) silently overwrites any docker-compose.yml already there; the finally then moves the bundled file into the project, so the parent's original file is destroyed rather than restored. A user running npx @dotcms/create-app from inside another compose project loses that file with no prompt.

🟡 applyStarterUrl treats $ in the starter URL as a replacement pattern — src/utils/starter-url.ts:37

return composeContents.replace(CUSTOM_STARTER_URL_LINE, `$1"${starterUrl}"`);

String.replace interprets $1, $&, $` etc. in the replacement string. Because starterUrl is interpolated into that string, a URL containing a $ sequence is rewritten incorrectly (e.g. $1 re-inserts capture group 1). Use a replacement function ((_, p1) => ${p1}"${starterUrl}"``) so the value is written literally.

🟡 Stale port list in troubleshooting output — src/utils/index.ts:660

getDockerDiagnostics still prints Check if ports 8082, 8443, 9200, and 9600 are available. This PR deliberately dropped 9200/9600 from REQUIRED_PORTS (the bundled compose file publishes neither), so this advice now points users at ports that are irrelevant to the failure.

📋 Existing Issues

None flagged — review scope is this PR's diff.

✅ Resolved

Both semgrep-dotcms High findings on this PR (axios Proxy-Authorization leak on cross-origin redirect) are resolved, not merely patched. Commit 962f589c removed the axios dependency entirely — src/api/index.ts and the UVE/readiness/health paths now use Node's native fetch via the new src/utils/http.ts, and no runtime axios usage remains (the remaining mentions are comments explaining why it was dropped). The semgrep annotations were scanned against an earlier SHA that still imported axios; the vulnerable code class is gone.

[semgrep-dotcms]

High severity vulnerability may affect your project—review required:
Line 221 lists a dependency (axios) with a known High severity vulnerability.

ℹ️ Why this matters

Affected versions of axios are vulnerable to Insertion of Sensitive Information Into Sent Data. The Node.js HTTP adapter in axios fails to clear the Proxy-Authorization header when a request that initially used an authenticated HTTP proxy is redirected to a target requiring no proxy (e.g. an HTTP-to-HTTPS redirect with no HTTPS proxy configured), leaking the proxy credentials to the final origin server.

References: https://euvd.enisa.europa.eu/vulnerability/EUVD-2026-36262, GHSA, CVE

To resolve this comment:
Check if you make requests with the Node.js HTTP adapter through an authenticated HTTP proxy with redirect following enabled.

• If you're affected, upgrade this dependency to at least version 1.16.0 at core-web/pnpm-lock.yaml.
• If you're not affected, comment /fp we don't use this [condition]

💬 Ignore this finding

To ignore this, reply with:

• /fp <comment> for false positive
• /ar <comment> for acceptable risk
• /other <comment> for all other reasons

If this is a critical or high severity finding, please also link this issue in the #security channel in Slack.

_{You can view more details on this finding in the Semgrep AppSec Platform here.}

[semgrep-dotcms]

High severity vulnerability may affect your project—review required:
Line 185 lists a dependency (axios) with a known High severity vulnerability.

ℹ️ Why this matters

Affected versions of axios are vulnerable to Insertion of Sensitive Information Into Sent Data. The Node.js HTTP adapter in axios fails to clear the Proxy-Authorization header when a request that initially used an authenticated HTTP proxy is redirected to a target requiring no proxy (e.g. an HTTP-to-HTTPS redirect with no HTTPS proxy configured), leaking the proxy credentials to the final origin server.

References: https://euvd.enisa.europa.eu/vulnerability/EUVD-2026-36262, GHSA, CVE

To resolve this comment:
Check if you make requests with the Node.js HTTP adapter through an authenticated HTTP proxy with redirect following enabled.

• If you're affected, upgrade this dependency to at least version 1.16.0 at core-web/pnpm-lock.yaml.
• If you're not affected, comment /fp we don't use this [condition]

💬 Ignore this finding

To ignore this, reply with:

• /fp <comment> for false positive
• /ar <comment> for acceptable risk
• /other <comment> for all other reasons

If this is a critical or high severity finding, please also link this issue in the #security channel in Slack.

_{You can view more details on this finding in the Semgrep AppSec Platform here.}

[semgrep-dotcms]

High severity vulnerability may affect your project—review required:
Line 58 lists a dependency (axios) with a known High severity vulnerability.

ℹ️ Why this matters

Affected versions of axios are vulnerable to Insertion of Sensitive Information Into Sent Data. The Node.js HTTP adapter in axios fails to clear the Proxy-Authorization header when a request that initially used an authenticated HTTP proxy is redirected to a target requiring no proxy (e.g. an HTTP-to-HTTPS redirect with no HTTPS proxy configured), leaking the proxy credentials to the final origin server.

References: https://euvd.enisa.europa.eu/vulnerability/EUVD-2026-36262, GHSA, CVE

To resolve this comment:
Check if you make requests with the Node.js HTTP adapter through an authenticated HTTP proxy with redirect following enabled.

• If you're affected, upgrade this dependency to at least version 1.16.0 at core-web/pnpm-lock.yaml.
• If you're not affected, comment /fp we don't use this [condition]

💬 Ignore this finding

To ignore this, reply with:

• /fp <comment> for false positive
• /ar <comment> for acceptable risk
• /other <comment> for all other reasons

If this is a critical or high severity finding, please also link this issue in the #security channel in Slack.

_{You can view more details on this finding in the Semgrep AppSec Platform here.}

[semgrep-dotcms]

High severity vulnerability may affect your project—review required:
Line 409 lists a dependency (axios) with a known High severity vulnerability.

ℹ️ Why this matters

Affected versions of axios are vulnerable to Insertion of Sensitive Information Into Sent Data. The Node.js HTTP adapter in axios fails to clear the Proxy-Authorization header when a request that initially used an authenticated HTTP proxy is redirected to a target requiring no proxy (e.g. an HTTP-to-HTTPS redirect with no HTTPS proxy configured), leaking the proxy credentials to the final origin server.

References: https://euvd.enisa.europa.eu/vulnerability/EUVD-2026-36262, GHSA, CVE

To resolve this comment:
Check if you make requests with the Node.js HTTP adapter through an authenticated HTTP proxy with redirect following enabled.

• If you're affected, upgrade this dependency to at least version 1.16.0 at core-web/pnpm-lock.yaml.
• If you're not affected, comment /fp we don't use this [condition]

💬 Ignore this finding

To ignore this, reply with:

• /fp <comment> for false positive
• /ar <comment> for acceptable risk
• /other <comment> for all other reasons

If this is a critical or high severity finding, please also link this issue in the #security channel in Slack.

_{You can view more details on this finding in the Semgrep AppSec Platform here.}