Malleable Thought Medium

Supabase + PowerSync Setup

This repo now expects:

• Supabase hosted Postgres for the source database
• Supabase Auth for app sessions (email OTP, with anonymous as a fallback)
• PowerSync Cloud for syncing into local SQLite

Sign-in flow:

• Primary: enter your email, Supabase emails a 6-digit code, type it back in the app
• Fallback: "Continue without an account" button performs an anonymous sign-in (per-device session, can't invite or be invited until you sign in with email)

One-Time Setup

1. Create a local env file from .env.example.
2. Log into Supabase:

npx supabase login

3. Create a hosted project, then link this repo to it:

npx supabase orgs list
npx supabase projects create knowledge-medium --org-id <org-id> --region us-west-1 --db-password <db-password>
npx supabase link --project-ref <project-ref> --password <db-password>

4. Push the committed schema and auth config:

npx supabase db push
npx supabase config push

5. Fill client env vars:

   • VITE_SUPABASE_URL: Supabase project URL
   • VITE_SUPABASE_ANON_KEY: Supabase publishable / anon key

6. Log into PowerSync and create a cloud instance:

npx powersync@latest login
npx powersync@latest link cloud --create --project-id <powersync-project-id>
npx powersync@latest validate
npx powersync@latest deploy

7. Fill the remaining env vars:

   • PS_DATABASE_URI: Supabase "Direct connection" URI copied from the Supabase Connect dialog
   • VITE_POWERSYNC_URL: PowerSync instance URL from the PowerSync dashboard / connect dialog

8. Start the app:

yarn dev

Local Database Migration Tests

Run the SQL migration test suite with:

yarn check:db

This starts a local Supabase Postgres test container, applies supabase/migrations/*.sql as supabase_admin, runs every pgTAP test in supabase/tests, and then removes the test database container so the next run starts clean. It is not part of yarn check; the pre-commit gate stays JS-only and does not require a container runtime.

For Apple Container, install container and socktainer. yarn check:db uses the shared runtime helper and starts the Apple container system plus a managed Socktainer process when DOCKER_HOST is unset:

yarn check:db

The runtime helper is also available directly:

yarn db:runtime:apple

That starts Apple Container/Socktainer and prints the Docker host it prepared. If DOCKER_HOST is already set, yarn check:db respects it. To force the default Docker runtime, set CHECK_DB_CONTAINER_RUNTIME=docker.

Notes

• The fastest dev path is to use the Supabase direct connection URI as-is in PS_DATABASE_URI.
• For a hardened setup, create a dedicated powersync_role with replication privileges and replace the username/password in PS_DATABASE_URI before deploying PowerSync.
• Because the starter graph is seeded in the remote database, the app will now wait briefly for the first remote sync before falling back to local example data.

Safe Mode

• Add ?safeMode to URL to disable dynamic renderer loading
• Only default renderers will be used
• Useful for debugging or when custom renderers are problematic

Agent Runtime Access

The app exposes a first-class runtime bridge for coding agents. The browser app connects to a local relay, and agents submit commands to that relay from the terminal. Commands execute inside the live app runtime, with access to the current Repo, active workspace, PowerSync SQLite database, resolved runtime facets, block helpers, and arbitrary JavaScript execution.

Start the app:

yarn dev

Then use the CLI from another terminal. If the local relay is not running, the CLI starts it in the background before submitting the command:

yarn agent connect
yarn agent ping
yarn agent sql all "SELECT id, content FROM blocks LIMIT 5"
yarn agent create-block '{"parentId":"<block-id>","content":"Created by agent"}'
yarn agent eval 'return { workspaceId: repo.activeWorkspaceId, user: repo.user }'

yarn agent connect prints an app URL, opens the token dialog when that URL is loaded, then waits for the copied token to be pasted back into the terminal. After that one-time pairing, normal yarn agent ... commands use the stored token automatically.

Available runtime-code bindings include repo, db, runtime, safeMode, sql, block, getBlock, getSubtree, createBlock, updateBlock, installExtension, actions, renderers, refreshAppRuntime, React, ReactDOM, window, and document.

By default the bridge uses http://127.0.0.1:8787. The bridge secret is stored in the local config file (~/.config/knowledge-medium/agent-bridge.json by default), so pairing is normally one-time per browser profile and app origin. Run yarn agent pair-url or foreground the relay with yarn agent:server to get a bridge-only pairing URL. Override the pairing target with AGENT_RUNTIME_APP_URL, the browser endpoint with VITE_AGENT_RUNTIME_URL, and the CLI endpoint with AGENT_RUNTIME_URL.

The bridge only accepts browser origins from loopback hosts and configured app origins. Add comma-separated entries with AGENT_RUNTIME_ALLOWED_ORIGINS; browser origins do not include URL paths, so GitHub Pages is allowed as https://stvad.github.io. Detailed /health output requires the bridge secret header; the CLI reads the persisted local secret automatically for yarn agent status.

---

Expanding the ESLint configuration

If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:

• Configure the top-level parserOptions property like this:

export default tseslint.config({
  languageOptions: {
    // other options...
    parserOptions: {
      project: ['./tsconfig.node.json', './tsconfig.app.json'],
      tsconfigRootDir: import.meta.dirname,
    },
  },
})

• Replace tseslint.configs.recommended to tseslint.configs.recommendedTypeChecked or tseslint.configs.strictTypeChecked
• Optionally add ...tseslint.configs.stylisticTypeChecked
• Install eslint-plugin-react and update the config:

// eslint.config.js
import react from 'eslint-plugin-react'

export default tseslint.config({
  // Set the react version
  settings: { react: { version: '18.3' } },
  plugins: {
    // Add the react plugin
    react,
  },
  rules: {
    // other rules...
    // Enable its recommended rules
    ...react.configs.recommended.rules,
    ...react.configs['jsx-runtime'].rules,
  },
})

License

This repository is licensed under the Elastic License 2.0. In short: you can use, copy, modify, and self-host the software freely; you may not offer it to third parties as a hosted or managed service that replicates a substantial part of its functionality.

The packages/agent-cli sub-package is licensed separately under the MIT License so it can be used as an open integration surface by third-party tooling.

See CONTRIBUTING.md for contribution terms, including the license grant that preserves the project's ability to relicense future versions.