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 previews to the CLI site deployment summary by waiting for screenshot finalization after a deployment reaches ready, fetching the image from the screenshots storage bucket via the console SDK, and rendering it in the terminal using terminal-image with forced ANSI fallback before framing it with a text border. The three concerns raised in prior review threads (spurious timeout on screenshot finalization, hasSiteDeploymentScreenshots requiring both screenshots, and missing KITTY_WINDOW_ID clearing) are all addressed in the current implementation.

Confidence Score: 5/5

Safe to merge — all prior P0/P1 concerns are resolved; only minor P2 style suggestions remain.

All three previously flagged issues (timeout extension, OR vs AND screenshot check, KITTY_WINDOW_ID restore) are correctly implemented. The two remaining findings are P2: visual width calculation using .length instead of stringWidth (minor misalignment risk in CJK locales) and the terminal-image exclusion from the Windows ARM64 pkg build (gracefully degraded). Neither blocks correctness or the primary deploy flow.

templates/cli/lib/commands/push.ts (frameTerminalPreview visual width), templates/cli/package.json (Windows ARM64 build exclusion)

Important Files Changed

Filename	Overview
templates/cli/lib/commands/push.ts	Adds screenshot finalization wait, terminal-image rendering, and framed preview summary; previous timeout/hasSiteDeploymentScreenshots/KITTY_WINDOW_ID issues are resolved; minor wide-character visual width concern in frameTerminalPreview.
templates/cli/lib/sdks.ts	Adds optional endpointOverride parameter to sdkForConsole so screenshot fetches can use the project's configured endpoint; minimal, correct change.
templates/cli/package.json	Adds terminal-image@^3.1.1 dependency and phin override; marks terminal-image external in all esbuild scripts — pkg-based Windows ARM64 build will silently lose screenshot preview.
templates/cli/package.json.twig	Twig template kept in sync with package.json — same dependency additions and build script changes.
templates/cli/bun.lock.twig	Lock file template regenerated via the prescribed update script to include terminal-image and its dependency tree.
templates/cli/package-lock.json.twig	npm lock file template regenerated to match the new terminal-image dependency.

_{Reviews (8): Last reviewed commit: "fix(cli): externalize terminal-image in ..." | Re-trigger Greptile}