Repository navigation
Description
Context
Follow-up to #4. integrations/clockify/localthought.ts and ClockifyLocalThought.tsx currently plug into data-browser's LocalThoughtExtension registry — a bespoke React component and a projection function imported directly into data-browser's own bundle. That coupling caused two real build breaks today (ontola/atomic-server PRs #1611/#1612): a devonian git-SHA dependency that never resolved from integrations/clockify and then stopped resolving at all once the dependency was dropped.
Decision (per discussion): move Clockify to data-browser's AppFrame/App-resource mechanism instead — genuinely decoupled, no server install, no stored secret, matching LocalThought's own design principle. This issue is the plan for that move, and records what's proven vs. what's new work, so a future session doesn't have to re-derive it.
What's confirmed, with evidence
AppFrame/hostStore.ts(browser/data-browser/src/chunks/AppPage/) is the right mechanism: anAppis a resource in the Atomic graph (not compiled, not installed on the server).AppPage/index.tsx:<AppFrame app={resource.subject} drive={drive} />. Reads ride the signed-in person's own read rights (hostStore.ts: "every read goes through this page's store — which means it sees exactly what the signed-in person sees"). Writes (create/save/destroy) are confined to the app's own subtree by default (parent ?? app) and go throughPOST /app-write, signed server-side by the app's own key but gated on the user being signed in — no secret ever reaches the iframe.- This is not the same thing as
@tomic/plugin's "packaged view" (PluginView.tsx/legacyViewAdapter.ts) — that one is the WASM/WASI-Preview-2 plugin system, compiled and installed on the AtomicServer itself (seeplugin-examples/test-plugin/:cargo build --target wasm32-wasip2, packaged as a zip,plugin.jsonmanifest). Re-coupling Clockify to that would reverse the LocalThought migration's whole premise. (I proposed this first and was wrong — corrected after actually readinglegacyViewAdapter.tsandplugin-examples/.) - Pets (
integrations/pets/) is a third, different thing again: a bundled integration, compiled intoatomic-server's own build (fetchIntegrationSource()fetchesplugin.jsfrom${server}/integrations/${id}/plugin.js, the server's own static route, embedded at build time byserver/build.rs::embed_integrations) and run server-side viaexecuteServerPlugin(the sandboxedmanifest/run(ctx)shape — the same model Clockify's old server-side plugin used before LocalThought). Not what we want for Clockify's execution, butConnectPets.tsx's install-flow pattern (ensureInstallationResourcebuilding a folder/table/view resource tree from a catalog entry + user config) is genuinely reusable regardless of execution model. catalog.json'spluginUrlfield is not what we need. Its documented meaning (integrations/catalog.json, theplugin-urlProperty resource): "Where this integration's source can be fetched from... for entries not bundled as a local package.json." It's a repo-attribution link (its one live usage pointsdevonian-google-calendarathttps://github.com/localthought/devonian, the whole repo) — and it's unused anywhere indata-browser's code today (grep -rn pluginUrl browser/data-browser/src→ nothing). We need a different, new catalog field: the URL to actually iframe as the App's entry point.@tomic/plugin's client SDK (RPCClient,browser/plugin/src/rpc.ts) doesn't fully cover the App protocol. It only exposesgetResource/query/commit/getPageContext/pickResource/pickFile/navigate/subscribe—commit()sends a'patch'op (viapackagedViewOperations), which is whatlegacyViewAdapter.ts(packaged views) handles. ButhostStore.ts(app views) doesn't have a'patch'case at all — it switches on raw'create'/'save'/'destroy'ops instead. So a Clockify app can't just useRPCClient.commit()for writes; it needscreate/save/destroymethods that don't exist on the client yet (or has to send rawviewRequest()calls itself in the meantime).- Nothing today wires a
catalog.jsonentry into a real installedAppresource, for any integration. This is genuinely new plumbing, not something to adapt from an existing generic flow.
What's not yet decided / needs building
- A new
catalog.jsonproperty for the App's entry-point URL (distinct frompluginUrl). RPCClient(or a Clockify-specific client) gainingcreate/save/destroymethods matchinghostStore.ts's app-protocol ops.- An install flow: catalog entry → create an
Appresource (+ whatever folder/table/view resources Clockify's data lives under), modeled onConnectPets.tsx'sensureInstallationResourcepattern but producing an App-kind installation instead of a sandboxed-run one. Where this lives (generic, reusable for any future App-based integration, vs. Clockify-specific) is an open design question. - The actual Clockify app: fetches via the LocalThought proxy (unchanged), runs
clockifyProjection/resolveClockifyReferences(already ported todevonian/platform-lenses/clockify, or keep the self-contained local copy currently inintegrations/clockify/localthought.ts— TBD which), computes deterministic subjects per entry (AtomicIdentityMap-style, matching the pattern used throughout this whole ecosystem), and creates/updates them via the app-write protocol. Renders its own Setup/Manage/Timer UI. - Hosting:
atomic-pluginsbuilds and publishes this app (e.g. alongside the existing gh-pagescatalog.json). - Removal: once the app works, delete
ClockifyLocalThought.tsx, Clockify's entry inlocalThoughtExtension.ts'sEXTENSIONSarray, and pruneintegrations/clockify/localthought.tsto whatever (if anything) is still shared.
Suggested phasing
- Phase 1 — Scaffold the app package in
atomic-plugins(entry HTML/TS using@tomic/plugin'sRPCClientfor reads/subscribe), prove theget-context/get-resourcehandshake works against a real drive, no writes yet. - Phase 2 — Add
create/save/destroycapability (client-side + verify againsthostStore.ts's actual behavior), port the fetch+projection+deterministic-write loop. - Phase 3 — Port Setup/Manage/Timer UI into the app.
- Phase 4 — New catalog field + install-flow wiring (catalog entry → real
Appresource), likely the largest, mostdata-browser-invasive phase — needs its own careful scoping given today's history. - Phase 5 — Remove old
LocalThoughtExtensionspecial-casing; e2e verification.
Related
- Timesheets #4 — Phase A: Project/Person enrichment (the projection/reference-resolution logic this migration carries forward)
- Delegate Clockify's schema lens to devonian atomic-server#1611, #1612 — the build breaks that motivated this move
🤖 Generated with Claude Code
Activity
Scaffold Clockify as a drive plugin (Phase 1)
michielbdejong commentedon Sep 21, 2026
Update: the hosting mechanism is now fully confirmed (
server/src/handlers/plugin_ui.rs), and it resolves the open questions from the issue body cleanly:plugin-source) on an Atomic resource, found by walking up the app resource'sparentchain (source_of()). The server serves that stored string back asapplication/javascripton request — it never fetches anything external itself.const plugin = await import(js_url); await plugin.view({root, store})— the module must export aview({root, store})function, not self-mount on load.store(getApp/getData/getResource/query/newResource/subscribe, resources withget/set/remove/save/destroy) is provided by the host at runtime via/plugin-ui?format=client(server/src/plugins/assets/view-client.js) — not something the plugin bundles or depends on.atomic-pluginsbuilds Clockify to a single JS file and publishes it (alongside the existingcatalog.json); at install time the browser fetches that file's text and writes it into a new App resource'splugin-sourceproperty (sameensureInstallationResourceshapeConnectPets.tsxalready uses) — so there's genuinely zero build-time dependency betweenatomic-server/data-browserandatomic-plugins, which was the whole point.Phase 1 done:
integrations/clockify/app/— a minimal drive-plugin scaffold (Vite library-mode build → singleui.js, exportsview(),store.tstypes hand-kept in sync withview-client.jssince there's no package for them yet). Verified: installs, typechecks, builds to one ES module that actuallyexport { ... as view }, and 2 vitest smoke tests pass against a stub store (loading state, then renders the app resource oncegetApp()resolves).Not yet done: writes (Phase 2, alongside porting the actual fetch+projection+write loop), the real Setup/Manage/Timer UI (Phase 3), and — the part with no existing precedent at all — the catalog-entry → installed-App-resource flow (Phase 4).
🤖 Generated with Claude Code
https://claude.ai/code/session_01Cng3r2ijbx8fBVZjLsEdH9
Generated by Claude Code
Fetch, project, and reconcile Clockify entries (Phase 2)
Document the drive-plugin pattern for future integrations
timesheets: port the Clockify drive-plugin app without a credential (#20
Guard against persisting LocalThought connection codes in the graph (#21
docs: nothing left to move for Clockify e2e; list the e2e quarantines (…
docs: nothing left to move for Clockify e2e; list the e2e quarantines (…
timesheets: port the Clockify drive-plugin app without a credential (#20
Merge pull request #59 from ontola/claude/issue-20-timesheets-drive-app
michielbdejong commentedon Sep 23, 2026
Handing off. Phases 1 and 2 are now on
mainasintegrations/timesheets/app/(PR #59). They replace the unmergedclaude/hopeful-hawking-kqlrdybranch, which should not be merged: it put the rotating code on the App resource (#21).Done here:
ProxyTransportthat looks for a hoststore.proxyop. Without it the app refuses to sync; it never falls back to holding a code.build.mjsproduces a single ~17 KB ES module exporting onlyview.timesheetslane, including against the shared Clockify mock.Left, and where:
hostStore.tspropValsvsview-client.jsprops: Plugin view bridge: hostStore replies with propVals but view-client.js reads result.props atomic-server#1640. Until it is fixed,resource.get()returns undefined in a real frame, so this app shows "not connected" and re-saves every row on each sync.pluginUrl;plugin-source, with a data table and real properties forontology.ts(modelled onConnectPets.tsx);dist/ui.jsnext tocatalog.json;data-browser.timesheetsvs the upstreamclockifykey, and the dead upstream Clockify e2e tests, are tracked under timesheets: move the two Clockify e2e tests here from atomic-server #44.Details are in
integrations/timesheets/README.md("Drive-plugin app").🤖 Generated with Claude Code