Repository navigation
docs(apps): say where preview app state lives and that it does not sync - #2647
Conversation
The shell saves an app's `prefs` and `appState` in the signed-in user's file store on the server the page is connected to, in a file named after the app id (`.workspace/<appId>.workspace.json`). The App Builder preview runs against the connected development server (`ROCKETRIDE_URI`), so the state it saves lives in that server's file store, while the published @me app lives on the deployment target: on different servers, or under another app id, each copy has its own file. When the deployment target is the development server and the user and app id are the same, both read one file but nothing syncs: each page keeps the copy it loaded and writes it back whole, so the last save wins. Files the app writes itself through the shell connection are per server and user, with no app id or version in the path. To a developer this looks exactly like data loss (#2468), and nothing in the docs said so. The separation is by design, per the 6 October review decision; this is a docs-only change: no UI, badge or tooltip. - ROCKETRIDE_APPS.md: a paragraph under State & Persistence saying which server "on the server" means, how versions, app ids and the preview relate to the state file, which user the preview is signed in as (Inherit Auth), and how app-written files are scoped; a one-line pointer from the Preview bullet of the Design panes. - Public App Builder guide: the same facts in the Design section. Refs #2468 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
🤖 Internal: Discord sync markerAuto-managed by the Discord notification workflow. Stores the linked Discord message ID and forum thread ID. Do not edit or delete. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info
📝 Walkthrough
Merge Risk: ⚪ Minimal · up to
|
asclearuc
left a comment
There was a problem hiding this comment.
Thank you @Leela8256 for writing this down.
The new State & Persistence text and the App Builder note explain the preview / @me split as "two files, not data loss", and I checked the claims against the code: the state file is keyed by app id only (appPath in useWorkspaceState.ts), each page writes its whole state back (debounced fsWriteJson), Inherit Auth defaults to on (DesignView.tsx), and a plain file path resolves to users/<client_id>/files (resolve_scope in file_store.py).
Approve
No inline comments.
… one allows (#3076) * docs(vscode): explain the connection modes, their names and what each one allows One mode has three names ("onprem" in settings, "Direct Connect" in the dropdown, "Direct" in the status bar), the status bar names neither the host nor what the mode allows, and the docs said little more (#2473). This explains the current behavior in the docs. Every statement was checked against develop. - usage.md: a new Connection Modes section. One table of the five modes with every name the extension shows for each, what runs where, what each needs (Docker and Service need Install on their panel the first time), and what publishing and developer registration do there. Deploying, publishing and registering go to the development connection's server, and the extension checks only that it is live. An open-source server (Local, Docker, Service) publishes under the fixed developer id "rocketride" without review and refuses developer registration. A RocketRide Cloud server needs a registered developer id and reviews @public releases. The section says which features use the development connection (running, the DEPLOY page, the App Builder) and which use the deployment connection. Subsections cover the status bar texts and where to see the host, and what switching modes changes, including the Cloud subscription gate on Run, the app namespace and the palette. - usage.md: "Deploying to Cloud" becomes "Deploying a Pipeline": the DEPLOY page publishes to the development connection's server, which is not always RocketRide Cloud. - usage.md: the .env Auto-Sync section now matches the code. Every mode syncs, Cloud included, the deployment connection writes its own ROCKETRIDE_DEPLOY_* pair, a Cloud sign-out empties the key, and the rocketride CLI reads .env too. It said only self-hosted development connections synced and that nothing was ever cleared. - installation.md: the Welcome steps list the five modes, say which mode takes a URL or key and that Docker and Service need Install first, name the Save & Connect button and link to the table; the hostUrl rows say only Direct Connect uses them. - index.md: the connection manager bullet and the connectionMode row point to the table; both hostUrl rows say only Direct Connect uses them. Re-verified against develop 7b687e4 after #2625 landed: the text now names the Settings page's Connections and Environment Variables sections and the sidebar menu, and no longer edits deployment-webview.md, whose postMessage protocol #2625 removed. Docs only, so no CHANGELOG entry, as for #2534, #2647 and #2613. #2625 kept the mode names: the status bar and the sidebar menu still read "Connected (Direct)" and name no host. Naming the mode and host in the UI is left for a code change. Closes #2473 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs(vscode): Linux libraries, first-run status texts and .env precedence Three gaps in the connection-modes text: the Local row said a user needs nothing, but on Linux the engine needs libc++1, libc++abi1 and libgomp1, which the extension checks at the first start and offers to install with apt; the Welcome steps said the status bar reads Disconnected before the Docker or Service install, but it reads Setup until the first save; and the .env section did not say that the Python SDK and the rocketride CLI leave a variable that is already in the process environment alone, so a pair exported before a target switch keeps pointing at the old server until it is unset or re-exported. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs(vscode): name the Linux libraries per distribution The Local row gave only the Debian and Ubuntu package names. It now names the libraries, the apt packages the extension offers to install, and the Fedora and RHEL packages (`libcxx`, `libcxxabi`, `libgomp`), the same names the self-hosting and development pages use. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
…nc (rocketride-org#2647) The shell saves an app's `prefs` and `appState` in the signed-in user's file store on the server the page is connected to, in a file named after the app id (`.workspace/<appId>.workspace.json`). The App Builder preview runs against the connected development server (`ROCKETRIDE_URI`), so the state it saves lives in that server's file store, while the published @me app lives on the deployment target: on different servers, or under another app id, each copy has its own file. When the deployment target is the development server and the user and app id are the same, both read one file but nothing syncs: each page keeps the copy it loaded and writes it back whole, so the last save wins. Files the app writes itself through the shell connection are per server and user, with no app id or version in the path. To a developer this looks exactly like data loss (rocketride-org#2468), and nothing in the docs said so. The separation is by design, per the 6 October review decision; this is a docs-only change: no UI, badge or tooltip. - ROCKETRIDE_APPS.md: a paragraph under State & Persistence saying which server "on the server" means, how versions, app ids and the preview relate to the state file, which user the preview is signed in as (Inherit Auth), and how app-written files are scoped; a one-line pointer from the Preview bullet of the Design panes. - Public App Builder guide: the same facts in the Design section. Refs rocketride-org#2468 Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Summary
@meapp keep separate saved state, which looks like data loss when switching between them (Design preview and the published@meapp hold separate appState #2468). In the 6 October review the lead ruled the separation is by design and asked for the reporter's use case before any UI change, so this is documentation only: no badge, no tooltip, no code.docs/agents/context/ROCKETRIDE_APPS.md(State & Persistence) and the App Builder guide now say where an app'sprefsandappStateare saved: in the signed-in user's file store on the connected development server, in.workspace/<appId>.workspace.json, keyed by app id only. The preview runs against the development server, so its state lives there; the published@meapp lives on the deployment target. A different server or app id means a different file; the same server, user and app id means one file that both read, with no sync and the last save winning, so finish in one, close it, then reload the other before editing there. With Inherit Auth on the preview is signed in as the App Builder is; with it off, as whoever signs in inside it. App-written files are per server and user, with no app id or version in the path.packages/shell/src/hooks/useWorkspaceState.ts(path, app-id key, debounced whole-state write, one load per connect),packages/ai/src/ai/account/file_store.pyandcmd_store.py(per-user tree),packages/shell/src/util/devMode.ts(the preview's session). Wording describes behaviour, not the server-side dev overlay, so it stays true when App Builder in the cloud: unified shell bus, devtool platform, local-first dev previews #2625 lands.Type
docs
Testing
python3 scripts/validate-client-docs.py;git diff --check; anchors match the table of contents; line wrap matches both files.Checklist
Linked Issue
Refs #2468 (the visual indicator the issue also asks for waits for the reporter's use case, per the 6 October review)
🤖 Generated with Claude Code
Summary by CodeRabbit