Skip to content

Move Clockify off LocalThoughtExtension onto an externally-hosted App #20

Closed

Description

@michielbdejong

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: an App is 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 through POST /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 (see plugin-examples/test-plugin/: cargo build --target wasm32-wasip2, packaged as a zip, plugin.json manifest). Re-coupling Clockify to that would reverse the LocalThought migration's whole premise. (I proposed this first and was wrong — corrected after actually reading legacyViewAdapter.ts and plugin-examples/.)
  • Pets (integrations/pets/) is a third, different thing again: a bundled integration, compiled into atomic-server's own build (fetchIntegrationSource() fetches plugin.js from ${server}/integrations/${id}/plugin.js, the server's own static route, embedded at build time by server/build.rs::embed_integrations) and run server-side via executeServerPlugin (the sandboxed manifest/run(ctx) shape — the same model Clockify's old server-side plugin used before LocalThought). Not what we want for Clockify's execution, but ConnectPets.tsx's install-flow pattern (ensureInstallationResource building a folder/table/view resource tree from a catalog entry + user config) is genuinely reusable regardless of execution model.
  • catalog.json's pluginUrl field is not what we need. Its documented meaning (integrations/catalog.json, the plugin-url Property 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 points devonian-google-calendar at https://github.com/localthought/devonian, the whole repo) — and it's unused anywhere in data-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 exposes getResource/query/commit/getPageContext/pickResource/pickFile/navigate/subscribe — commit() sends a 'patch' op (via packagedViewOperations), which is what legacyViewAdapter.ts (packaged views) handles. But hostStore.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 use RPCClient.commit() for writes; it needs create/save/destroy methods that don't exist on the client yet (or has to send raw viewRequest() calls itself in the meantime).
  • Nothing today wires a catalog.json entry into a real installed App resource, for any integration. This is genuinely new plumbing, not something to adapt from an existing generic flow.

What's not yet decided / needs building

  1. A new catalog.json property for the App's entry-point URL (distinct from pluginUrl).
  2. RPCClient (or a Clockify-specific client) gaining create/save/destroy methods matching hostStore.ts's app-protocol ops.
  3. An install flow: catalog entry → create an App resource (+ whatever folder/table/view resources Clockify's data lives under), modeled on ConnectPets.tsx's ensureInstallationResource pattern 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.
  4. The actual Clockify app: fetches via the LocalThought proxy (unchanged), runs clockifyProjection/resolveClockifyReferences (already ported to devonian/platform-lenses/clockify, or keep the self-contained local copy currently in integrations/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.
  5. Hosting: atomic-plugins builds and publishes this app (e.g. alongside the existing gh-pages catalog.json).
  6. Removal: once the app works, delete ClockifyLocalThought.tsx, Clockify's entry in localThoughtExtension.ts's EXTENSIONS array, and prune integrations/clockify/localthought.ts to whatever (if anything) is still shared.

Suggested phasing

  • Phase 1 — Scaffold the app package in atomic-plugins (entry HTML/TS using @tomic/plugin's RPCClient for reads/subscribe), prove the get-context/get-resource handshake works against a real drive, no writes yet.
  • Phase 2 — Add create/save/destroy capability (client-side + verify against hostStore.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 App resource), likely the largest, most data-browser-invasive phase — needs its own careful scoping given today's history.
  • Phase 5 — Remove old LocalThoughtExtension special-casing; e2e verification.

Related


🤖 Generated with Claude Code

https://claude.ai/code/session_01Cng3r2ijbx8fBVZjLsEdH9

Activity

  1. michielbdejong commented on Sep 21, 2026

    @michielbdejong
    ContributorAuthor

    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:

    • A drive plugin (App-kind) stores its entire compiled JS as a string property (plugin-source) on an Atomic resource, found by walking up the app resource's parent chain (source_of()). The server serves that stored string back as application/javascript on request — it never fetches anything external itself.
    • The host's generated shell does const plugin = await import(js_url); await plugin.view({root, store}) — the module must export a view({root, store}) function, not self-mount on load. store (getApp/getData/getResource/query/newResource/subscribe, resources with get/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.
    • No separate CSS file for a drive plugin ("a plugin in the drive is one module") — styles have to be inlined.
    • This confirms the actual install flow: atomic-plugins builds Clockify to a single JS file and publishes it (alongside the existing catalog.json); at install time the browser fetches that file's text and writes it into a new App resource's plugin-source property (same ensureInstallationResource shape ConnectPets.tsx already uses) — so there's genuinely zero build-time dependency between atomic-server/data-browser and atomic-plugins, which was the whole point.
    • (For the record: I got the hosting mechanism wrong twice before landing here — first guessing it was the WASM "packaged view" system, then guessing it was a live externally-iframed URL. Both wrong; this is the real one, verified by reading the Rust handler directly.)

    Phase 1 done: integrations/clockify/app/ — a minimal drive-plugin scaffold (Vite library-mode build → single ui.js, exports view(), store.ts types hand-kept in sync with view-client.js since there's no package for them yet). Verified: installs, typechecks, builds to one ES module that actually export { ... as view }, and 2 vitest smoke tests pass against a stub store (loading state, then renders the app resource once getApp() 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

  2. michielbdejong commented on Sep 23, 2026

    @michielbdejong
    ContributorAuthor

    Handing off. Phases 1 and 2 are now on main as integrations/timesheets/app/ (PR #59). They replace the unmerged claude/hopeful-hawking-kqlrdy branch, which should not be merged: it put the rotating code on the App resource (#21).

    Done here:

    • The App resource stores only a connection reference: connection id, workspace id, user id and look-back days. No secret.
    • All proxy traffic goes through an injected ProxyTransport that looks for a host store.proxy op. Without it the app refuses to sync; it never falls back to holding a code.
    • Projection uses the devonian Clockify lens. Rows are matched by a stored entry id, limited to children of the app's data table, and it is import only.
    • build.mjs produces a single ~17 KB ES module exporting only view.
    • Unit tested in the timesheets lane, including against the shared Clockify mock.
    • Not verified: loading in a real host, or calls to the real proxy.

    Left, and where:

    Details are in integrations/timesheets/README.md ("Drive-plugin app").

    🤖 Generated with Claude Code

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions