Skip to content

Pin the device checkout to the Server's revision (#435, HUABU-CLOUD-07) - #439

Open
Yuge Zhang (ultmaster) wants to merge 4 commits into
microsoft:mainfrom
ultmaster:fix/issue-435-device-handoff
Open

Yuge Zhang (ultmaster) wants to merge 4 commits into
microsoft:mainfrom
ultmaster:fix/issue-435-device-handoff

Conversation

@ultmaster

@ultmaster Yuge Zhang (ultmaster) commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

The easy half of HUABU-CLOUD-07 from #435: Connect device now tells a device to check out the exact revision the Server runs, and the shell picker defaults to the viewer's platform. Split out of #438 on request. The versioned standalone device client (the architecture half of 07) is not in scope.

  • Revision source: reuses the existing HUABU_DEPLOYED_SHA, which until now only the owner-only Canary status read. Docker images set it from the SOURCE_REVISION build argument, and scripts/start-web.mjs fills it from git rev-parse HEAD when unset. A single deployedSha() in canary-redeploy.ts reads it for both Canary and readiness.
  • API: GET /api/deployment/readiness gains an optional revision: the full 40-character commit, or null when unset or not a full SHA. Older servers leave it out, which reads as unknown.
  • Connect device: with a revision, the setup commands become git clone …, cd Huabu, git checkout <full sha>, pnpm install, and the text names the short SHA. Without one, the commands stay unpinned and the text says the Server doesn't report its exact revision.
  • Shell picker: starts on PowerShell when the browser platform is Windows, Bash/Zsh otherwise; still switchable.
  • Members and freshness: Settings loads readiness only for people who manage the deployment, and the store outlives the page, so Connect device revalidates readiness each time it opens (joining a load already in flight). While that load is pending it shows the generic text rather than a cached SHA. Without this a Bubble member, the main person connecting a device in the cloud, never saw the pin, and after a redeploy could be shown the old commit.

Behaviour changes to review

  • Every signed-in person can now read the deployed commit SHA through readiness, not only the owner.
  • The pinned checkout only works if the deployed commit exists on microsoft/Huabu. An image built from an unpushed fork commit shows a SHA that can't be checked out.

Verification

  • pnpm run lint (0 errors), format:check, typecheck, check:i18n, check-headers, and pnpm run test across all packages pass.
  • Tests added: readiness passes the revision through and accepts only a full commit. In the web component: pinned checkout, null and absent revision, readiness not yet loaded, loading readiness when nothing else has, revalidating a revision an earlier load left (fails against the previous behaviour), joining a load in flight, and the default shell on Win32, Linux and macOS. The pinned-checkout and Win32 tests fail against the old component.
  • Real browser (Playwright/Chromium) against a local Bubble-mode server on this branch, with Postgres in a disposable container and HUABU_DEPLOYED_SHA set to a real upstream commit. Readiness returned the revision. Connect device showed "the exact revision this server runs (0b4438c)" and git checkout 0b4438c81f7fb5562dac8f96b19a80302c7f5d15 before pnpm install. With the platform reported as Win32 the picker started on PowerShell, otherwise on Bash/Zsh. With readiness stubbed to revision: null, the commands were unpinned with the unknown-revision explanation.
  • Second pass with real sign-in (an Auth0 member and an Entra owner, test accounts created for this) and HUABU_DEPLOYED_SHA set to this branch's head. The member's readiness returned the revision, but Connect device showed the unpinned commands, because only owners loaded readiness. That is fixed in 56546ef: the member now sees git checkout <sha>, and the owner still does with a single readiness request.

Not verified

  • A real deployed image built with SOURCE_REVISION, and an actual device connecting from a pinned checkout.
  • A real Windows browser (the platform was overridden in Chromium).

Refs #435

🤖 Generated with Claude Code

…crosoft#435)

A device has to run Huabu source that matches the Server, but nothing
told it which commit the Server runs. The image already bakes the commit
into `HUABU_DEPLOYED_SHA` (from `SOURCE_REVISION`), and a source checkout
fills it from `git rev-parse HEAD`; only the owner-only Canary status
read it.

`deployedSha()` now owns reading that variable, and the readiness
response every signed-in person's Settings already loads carries it as
`revision` (null when unknown, absent from older servers).

Part of microsoft#435 (HUABU-CLOUD-07).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…#435)

Connect device asked for source matching the Server but showed an
unpinned clone, and its shell picker always started on Bash/Zsh, even in
a Windows browser.

- When readiness reports the Server's commit, the setup commands check
  out exactly that revision before `pnpm install`, and the text names
  it. When the Server does not report one, the commands stay unpinned
  and the text says the revision is unknown. Before readiness loads, the
  generic text is unchanged.
- The shell picker starts on PowerShell in a Windows browser and on
  Bash/Zsh elsewhere; it can still be switched.

Part of microsoft#435 (HUABU-CLOUD-07).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 11:12

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Fresh non-owner sessions show unpinned Connect device commands despite a valid server SHA because readiness is loaded only for deployment managers.

1 open issue
What changed in this PR

Addresses the device-onboarding portion of HUABU-CLOUD-07 by using the Server’s deployed revision for matching source checkouts. The standalone device client remains out of scope.

Changes:

  • Exposes an optional full commit SHA through deployment readiness, reusing Canary’s revision validation.
  • Adds pinned checkout instructions and localized fallback text when the revision is unknown.
  • Defaults the shell picker to PowerShell on Windows and adds revision and platform coverage.
File Description
packages/​shared/​src/​types/​api/​deployment.ts Adds the optional, nullable revision contract.
docs/​architecture/​canary-deployment.md Documents revision reporting and device checkout behavior.
apps/​web/​src/​utils/​platform.ts Adds Windows platform detection.
apps/​web/​src/​i18n/​resources/​zh-CN/​common.json Adds Chinese revision guidance.
apps/​web/​src/​i18n/​resources/​en/​common.json Adds English revision guidance.
apps/​web/​src/​components/​Settings/​sections/​ExternalAgentRuntimeSettings.tsx Displays pinned checkout commands and selects the default shell.
apps/​web/​src/​components/​Settings/​sections/​ExternalAgentRuntimeSettings.test.tsx Covers revision states and platform-specific shell defaults.
apps/​server/​src/​modules/​security/​deployment.route.ts Includes the deployed revision in readiness responses.
apps/​server/​src/​modules/​security/​deployment.route.test.ts Tests revision reporting and SHA validation.
apps/​server/​src/​modules/​security/​canary-redeploy.ts Shares the deployed-SHA reader between Canary and readiness.

Review effort: Balanced

…t#435)

Settings loads deployment readiness only for people who manage the
deployment, so a Bubble member opening Connect device never received the
Server's revision and got the unpinned checkout. Found signing in a real
Auth0 member against a local Bubble server. The Connect device section
now loads readiness once on mount when nothing else has.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 16:03

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Connection instructions retain a stale server revision for Bubble members across reopening, potentially recommending an outdated git checkout as the exact running revision after a server update.

1 open issue
1 resolved since last review

Review effort: Balanced

@ultmaster

Copy link
Copy Markdown
Collaborator Author

Test coverage

Head tested: 56546eff17e6b00024044c0316baa6e07b40dcb0 (all three commits).

Automated

  • Full pnpm run check at 534ea8766: lint (0 errors), format, typecheck, all package tests (server 3588, web 5786), deployment tests, i18n and headers.
  • After 56546eff1, which only touches web files: lint and format on the changed files, web typecheck and the full web suite (5788) pass.
  • New tests:
    • Readiness passes the revision through, and only for a full 40-character commit.
    • Connect device:
      • Pinned checkout.
      • Null and absent revision (unpinned, with the explanation).
      • Generic text while loading.
      • Loading readiness itself when nothing else has, and not reloading it when it is already loaded.
      • Default shell on Win32, Linux and macOS.
    • The pinned-checkout and Win32 tests fail against the old component.

Real browser

Playwright/Chromium against a local server on this branch: Bubble identity with the real Auth0 and Entra authenticators, Postgres in a disposable container, and HUABU_DEPLOYED_SHA set to a real commit.

  • First pass (loopback default driver, owner):
    • Readiness returned the revision, and Connect device showed the short SHA plus git checkout <full sha> before pnpm install.
    • A Win32 platform started the picker on PowerShell.
    • With revision: null, the commands were unpinned and the explanation appeared.
  • Second pass (real sign-in, an Auth0 member and an Entra owner):
    • The member's readiness returned the revision, but Connect device showed unpinned commands, because Settings loaded readiness only for owners.
    • 56546eff1 fixes this. After the fix, the member sees git checkout 534ea87663ec9ce4764d9353281df0d6144a82d3, and the owner still sees it with a single readiness request.

Not covered

  • A deployed image built with SOURCE_REVISION, and a real device connecting from a pinned checkout.
  • A real Windows browser (the platform was overridden in Chromium).

🤖 Generated with Claude Code

…rosoft#435)

The readiness store outlives the Settings page and only owners refresh
it, so a member who opened Connect device before a redeploy kept being
told to check out the old commit as "the exact revision this server
runs". Connect device now asks again on every open, joining a load
already in flight, and shows the generic text rather than a possibly
stale SHA while it waits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 18:10

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified in the changes to pin device setup instructions to the Server’s reported revision.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants