calva-backseat-driver: Instructions file for GitHub Copilot

Backseat Driver Source Conventions

Naming Conventions

• function! — side effects
• function+ — returns promise
• function!+ — side effects and promise
• function? — predicate
• !atom-name — atom (e.g., !app-db, !output-conn)
• ax. prefix — pure action handler
• fx. prefix — impure effect handler
• ex/ namespace — framework plumbing, not domain logic

Ex Framework Patterns

Actions (axs.cljs)

Actions are pure functions. They receive immutable state and arguments, return a map of changes:

{:ex/db  new-state        ;; state update (merged at end)
 :ex/dxs [[:ns/ax.name ...]]  ;; deferred actions (dispatched after state update)
 :ex/fxs [[:ns/fx.name ...]]} ;; effect declarations (executed after dxs)

Actions never access atoms, VS Code APIs, or external state directly. Use enrichment placeholders:

• :context/some.path — resolved from VS Code extension context
• [:db/get :key] — resolved from current app-db state
• :vscode/config.settingName — resolved from VS Code configuration

Effects (fxs.cljs)

Effects are impure handlers that receive dispatch!, context, and the enriched effect vector. They perform side effects and may dispatch new actions:

(defn some-effect! [dispatch! context [_ args]]
  (-> (some-async-operation!+ args)
      (.then (fn [result]
               (dispatch! context [[:ns/ax.handle-result result]])))))

Async Continuation

Effects return promises. Continuation actions use :ex/then, :ex/on-success, :ex/on-error with placeholder enrichment:

;; In action — declare effect with continuation
{:ex/fxs [[:ns/fx.do-thing {:data data
                             :ex/then [[:ns/ax.thing-done :ex/action-args]]}]]}

;; In effect — enrich continuation and dispatch
(.then promise
  (fn [result]
    (dispatch! context (ax/enrich-with-args then-actions result))))

Routing

Actions route by (namespace action-keyword): "app", "mcp", "db", "vscode", "node", "calva". Effects route similarly. Add new routes in ex/ax.cljs (handle-action) and ex/fx.cljs (perform-effect!).