Migrate Paseo plugin to v0.8's split client/server/shared architecture - #6
Merged
Merged
Conversation
Fixes the real, user-reported breakage: after updating Paseo to 0.8.0, the installed sessionforge plugin failed to load with "Plugin \"sessionforge\" requires Paseo <0.8.0. [...] Ask its author to migrate it." Reproduced the exact same error locally against a real Paseo 0.8.0 daemon before starting. Fetched the current v0.8 migration guide and reference docs (not relying on memory, since this is a real breaking API change) to get the actual new module shapes right: - paseo-plugin.json: added requirements.paseo: ">=0.8.0" (missing the field at all defaults to "<0.8.0", which is exactly what broke) - Split the old single index.ts into index.client.tsx (surface/sidebar/ command-center registration) and index.server.ts (RPC handler registration + the background-rescan cleanup hook) - Moved main.client.tsx -> client/sessions.tsx, src/server/session-handlers. server.ts -> server/session-handlers.ts, src/server/session-contracts. shared.ts -> shared/session-contracts.ts, per the new "the directory is the boundary" rule - Updated imports for the new module split: useRpc/PluginSurfaceProps now from @getpaseo/plugin/client (were @getpaseo/plugin); defineRpc now from the shared root @getpaseo/plugin (was @getpaseo/plugin/server) - Rewrote paseo-plugin.d.ts's hand-written ambient type declarations to match the new @getpaseo/plugin / @getpaseo/plugin/client / @getpaseo/plugin/server module split (there's no real installed @getpaseo/plugin package here to pull types from — Paseo supplies the real runtime at install time, this project has always hand-declared its own types against it) - Updated scripts/package-plugin.mjs's staged file list for the new layout Also discovered while testing this for real: Paseo 0.8's build step now scans the *entire* given plugin directory and rejects any file outside client/server/shared — including this monorepo's own unrelated packages/cli/dist/**. That means the previously-documented "point paseo straight at the repo root for local dev" flow no longer works at all here; only the packaged, self-contained bundle from `npm run package:plugin` does. Updated docs/MANUAL.md and CONTRIBUTING.md to document the actual working dev loop (package:plugin, then install/reload against build/paseo-plugin, not the repo root). Verified for real against the actual installed Paseo 0.8.0 daemon, not just a clean typecheck: installed the packaged bundle standalone (paseo plugin ls reports "running", clean logs), then used it to fix the actual broken "sessionforge" registration on this machine (same daemon that produced the original error), and separately verified the edit -> repackage -> reload dev loop actually picks up source changes. Also fixed an unrelated but real test-fragility bug found along the way: discover.server.test.ts's "keep-session" fixture used a hardcoded absolute date instead of one relative to "now", so it silently flipped from KEEP to ARCHIVE (crossing classifySession's 14-day threshold) as real time passed, breaking 3 tests that depended on it. Made the fixture dates relative to test-run time instead, so this can't happen again.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d3e1633281
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| The manual way — needed if you're developing the plugin itself, since it points `paseo` straight at your | ||
| working tree instead of a downloaded release snapshot: | ||
| The manual way — needed if you're developing the plugin itself. **Point `paseo` at `build/paseo-plugin`, not |
There was a problem hiding this comment.
This migration makes paseo plugin install /path/to/sessionforge fail for a repository checkout, as this new section explains, but README.md:54-56 and README.ko.md:54-56 still direct plugin developers to use exactly that command. Users following the project landing page will therefore hit the v0.8 module-location rejection instead of staging the plugin first; update those links/text to use npm run package:plugin and build/paseo-plugin.
Useful? React with 👍 / 👎.
4aMgLn4
approved these changes
Sep 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
After updating Paseo to 0.8.0, the installed
sessionforgeplugin fails to load:Reproduced this exact error locally against a real Paseo 0.8.0 daemon before starting the fix.
What changed
paseo-plugin.json: addedrequirements.paseo: ">=0.8.0"index.tsintoindex.client.tsx(surface/sidebar/command-center) andindex.server.ts(RPChandlers + cleanup)
client//server//shared/layout Paseo 0.8 requiresuseRpc/PluginSurfacePropsfrom@getpaseo/plugin/client;defineRpcfrom the shared root@getpaseo/plugin)paseo-plugin.d.ts's hand-written ambient types to match the new module splitscripts/package-plugin.mjs's staged file listAlso discovered while verifying this for real
Paseo 0.8's build step scans the entire plugin directory and rejects anything outside
client//server//shared/— including this monorepo's own unrelatedpackages/cli/dist/**. Thepreviously-documented "point
paseoat the repo root for local dev" flow is now completely broken; onlythe packaged bundle from
npm run package:pluginworks. Updateddocs/MANUAL.mdandCONTRIBUTING.mdwith the actual working dev loop.
Also fixed an unrelated but real bug found along the way:
discover.server.test.ts's fixture used ahardcoded absolute date instead of a relative one, so it silently broke 3 tests as real time passed a
14-day classification threshold. Made it relative to test-run time.
Verification
(
paseo plugin ls→running, clean logs), then used it to fix the actual brokensessionforgeregistration on this machine
npm run typecheckandnpm test(134/134) both passNote for the maintainer
This needs a new tagged release (
git tag vX.Y.Z && git push origin vX.Y.Z) once merged, sosessionforge wire-paseodistributes the fix to anyone else who's hit this.