fix(cli): say which build output is missing, not just "no index.html"

[claude]

Note

Description

When a deploy on the deployments-API lane finds no index.html at the output root, it threw a single message — "No index.html found ... a static site needs one at the output directory root" — for four distinct situations: no output at all, a missing output directory, an empty one, and one whose entry point sits a level down. That message asserted a site type the caller never chose and hid the real cause (a full-stack build that failed to emit .wrangler/deploy/config.json falls into the same no-worker arm), which sent a production publish failure hunting for a routing bug that did not exist. This PR splits the diagnosis into four specific messages with actionable hints, while keeping the throw and the INVALID_INPUT error code the platform’s publish alerting keys on unchanged.

Related Issue

None

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• packages/cli/src/core/site/deployment.ts: extracted the failure path out of readIndexHtml() into a new missingIndexHtmlError() that distinguishes four causes:
  • no worker artifact and no site.outputDirectory → "No site output to deploy", hinting how to set site.outputDirectory in config.jsonc
  • output directory missing → "Output directory does not exist", with the base44 build hint
  • output directory empty → "No files found in output directory", with the same hint
  • populated but no root entry point → "No index.html at the root", reporting the file count and naming any **/index.html found deeper, plus a hint that a build emitting .wrangler/deploy/config.json would have shipped its server
• The missing/empty output-directory checks restore the guard rails the legacy tar.gz upload (deploySite()) already had and that this lane had dropped.
• Hints ride the existing --json error envelope, which is the platform publish sandbox’s only view of a failed deploy.
• Added packages/cli/tests/cli/site_deploy_output_diagnostics.spec.ts (4 cases) covering each message, asserting each fails before the deployment create call and that the --json envelope keeps INVALID_INPUT and carries the nested-path hint.
• Updated docs/deployments.md with a "When there is no index.html to finalize with" section (condition→message table), a note that the error code must not change, new keywords, and a pointer to the new spec.

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

Checklist

• My code follows the project’s style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated docs/ (AGENTS.md) if I made architectural changes

Additional Notes

Diagnosis only — no control-flow change: every case that failed before still fails, at the same point, with the same InvalidInputError / INVALID_INPUT code. The .wrangler/deploy/config.json path is spelled out as a literal in copy rather than reused from WRANGLER_REDIRECT_PATH, since that constant is built with join() and would render with backslashes on Windows. The new spec mutates the copied with-site fixture (nesting the index.html, emptying the directory, removing it) rather than adding new fixtures. Build and test commands could not be executed in this environment, so the "tested locally"/"all tests pass" boxes are left unchecked for a human to confirm.

---

_{🤖 Generated by Claude | 2026-09-10 13:20 UTC | 5a268b0}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.14-pr.619.5a268b0

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.1.14-pr.619.5a268b0"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.14-pr.619.5a268b0"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.14-pr.619.5a268b0
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}