Add terminal screenshot previews to CLI site deployments

[ChiragAgg5k]

Summary

This PR adds a terminal-rendered screenshot preview to the CLI site deployment summary and aligns the CLI deploy flow with the console's screenshot finalization behavior.

Specifically, it:

• waits briefly after a site deployment becomes ready so late-arriving screenshotLight / screenshotDark file IDs can still be picked up
• fetches the deployment screenshot from the screenshots storage bucket through the console SDK
• renders a single framed terminal preview in the CLI summary using terminal-image
• shows the screenshot preview before the preview/deployment links
• keeps the preview output readable by preferring one screenshot instead of printing redundant light/dark variants
• adds the console endpoint override needed for screenshot preview fetches in CLI flows
• updates the CLI dependency templates and lockfile templates for terminal-image@^3.1.1

Problem

The CLI already streamed realtime build logs for site deployments, but it did not surface the deployment screenshot that the backend writes after the build completes. The console already treats this screenshot as part of the deployment lifecycle: deployment updates arrive over realtime, the deployment can sit in a short "ready but screenshots not attached yet" finalization state, and the frontend renders the screenshot once the file IDs are present.

The initial text-only ASCII experiment was not readable enough for real deployment previews, and separate light/dark sections added noise without improving the CLI output. The CLI needed a preview flow that was both faithful to the backend behavior and useful in an actual terminal.

Implementation Details

Deployment flow

The site push command now mirrors the console behavior more closely:

• when a site deployment reaches ready, the CLI reads screenshotLight and screenshotDark from the deployment payload
• if either screenshot is still missing, the CLI waits for up to 30 seconds in a finalizing state before giving up and continuing
• if screenshots still are not present after that window, the deploy still succeeds and the CLI emits a hint instead of failing

Screenshot fetching and rendering

Once a screenshot file ID exists, the CLI:

• creates a console-authenticated storage client using the active endpoint
• requests a PNG preview from the screenshots bucket
• renders one screenshot in the deployment summary, preferring dark mode and falling back to light mode if needed
• wraps the rendered output in a text border so the preview has a clear boundary in the terminal
• prints the preview before the preview/deployment links, with extra spacing to separate the sections cleanly

Why terminal-image

The previous plain-character renderer was not good enough for real screenshots. terminal-image produces a much more legible terminal thumbnail, but its native terminal-specific inline image modes are not a good fit for a boxed, portable CLI summary. The implementation therefore forces the package onto its ANSI fallback path before framing the preview, which keeps the output predictable across terminals while still producing a much better preview than grayscale ASCII text.

Dependency choice

terminal-image is pinned to ^3.1.1 in the CLI templates because that line is compatible with the CLI's Node 18 target. The template lockfiles were regenerated to match.

Files Changed

• templates/cli/lib/commands/push.ts
  • adds screenshot finalization handling, preview fetching, terminal rendering, and summary layout updates
• templates/cli/lib/sdks.ts
  • allows overriding the console endpoint so screenshot preview fetches use the correct base URL
• templates/cli/package.json
• templates/cli/package.json.twig
• templates/cli/package-lock.json.twig
• templates/cli/bun.lock.twig
  • add terminal-image and sync generated dependency metadata

Verification

I verified the change with both generation/linting and an end-to-end CLI deploy flow:

• php example.php cli console
• composer lint-twig
• cd examples/cli
• bun run mac-arm64
• ./build/appwrite-cli-darwin-arm64 push site
  • selected the existing Testing deployment logs site
  • answered Yes to deploy
  • answered Yes to activate the deployment
• confirmed that the final deploy summary renders a single screenshot preview and then prints the preview/deployment links underneath it

Screenshots

[greptile-apps]

Greptile Summary

This PR adds terminal screenshot preview rendering to the CLI site deployment summary. The implementation mirrors the console's finalization behavior: it extends the outer timeout when screenshots are still pending, waits up to 30 s for them to arrive, then falls back gracefully with a hint. The terminal-image package is lazily loaded and correctly marked as --external for the npm/esbuild builds, and the environment-variable save/restore block now covers KITTY_WINDOW_ID alongside the other terminal-detection variables. All three concerns raised in prior review threads are resolved in the current code.

Confidence Score: 5/5

Safe to merge; all previously flagged P1 concerns are addressed and only a minor dead-constant nit remains.

The spurious-timeout fix (extending timeoutDeadline), the OR-logic fix in hasSiteDeploymentScreenshots, and the KITTY_WINDOW_ID restore are all present in the current diff. The sole remaining finding is a P2 code-quality note about an unused MAX_WIDTH constant that has no runtime impact.

No files require special attention.

Important Files Changed

Filename	Overview
templates/cli/lib/commands/push.ts	Adds screenshot finalization wait, terminal image rendering pipeline, and framed preview in the deploy summary; all three previously flagged concerns (spurious timeout, OR vs AND for screenshots, KITTY_WINDOW_ID restore) are now addressed in the current code.
templates/cli/lib/sdks.ts	Adds optional endpointOverride to sdkForConsole so the screenshot fetch uses the project's configured endpoint rather than the global default; change is minimal and correct.
templates/cli/package.json	Adds terminal-image@^3.1.1 to dependencies and correctly marks it as --external in all esbuild npm-build targets so it is resolved from node_modules at runtime.
templates/cli/package.json.twig	Template mirror of package.json with the same terminal-image addition and --external flags; consistent with the static file.
templates/cli/bun.lock.twig	Adds terminal-image and its transitive dependencies to the bun lockfile template; no correctness concerns.
templates/cli/package-lock.json.twig	Adds terminal-image entries to the npm lockfile template; mechanical lockfile change consistent with the dependency addition.

_{Reviews (6): Last reviewed commit: "Sync CLI package manifests" | Re-trigger Greptile}