feat(inference): add native Anthropic (Claude) provider

.claude/superpowers/specs/2026-04-12-postgresql-review-fixes-design.md

@@ -0,0 +1,83 @@
+# PostgreSQL PR Review Fixes -- Design Spec
+
+**Date:** 2026-04-12
+**PR:** #4 (feat: add PostgreSQL as configurable database backend)
+**Scope:** One targeted fix from code review -- DB type safety. Plus documentation of a reviewed-and-validated design decision.
+
+## Issue 1 (resolved -- no change needed): `schema.relations.ts` imports from `./schema.sqlite`
+
+### Original concern
+
+`schema.relations.ts` imports table objects from `./schema.sqlite`, meaning relations are always defined against SQLite table objects, even when PostgreSQL is active.
+
+### Why this is correct
+
+Drizzle resolves relations to tables by **SQL table name** (via `getTableUniqueName` which returns `"schema.tableName"`, e.g. `"public.user"`), **not** by JavaScript object identity. When `drizzle()` receives `{ ...pgSchema, ...relations }`, it matches `userRelations` (defined with SQLite's `users` table) to PG's `users` table because both share the SQL name `"public.user"`.
+
+Changing the import to `./schema` was attempted but creates a **circular dependency**: `schema.relations.ts` -> `./schema` -> `export * from "./schema.relations"`. Node.js returns partially-initialized exports, causing `undefined` table objects at runtime.
+
+### No change needed
+
+The existing import from `./schema.sqlite` is the correct design.
+
+## Issue 2: Type safety of the `BetterSQLite3Database` cast
+
+### Problem
+
+In `drizzle.ts:133-136`, the PostgresJsDatabase instance is cast to `BetterSQLite3Database<FullSchema>` via `as unknown as`:
+
+```ts
+export const db: BetterSQLite3Database<FullSchema> =
+  dialect === "postgresql"
+    ? ((await createPostgresDB()) as unknown as BetterSQLite3Database<FullSchema>)
+    : ((await createSqliteDB()) as unknown as BetterSQLite3Database<FullSchema>);
+```
+
+Drizzle has no shared base type between SQLite and PG. The cast works at runtime because the query builder APIs are structurally compatible. However, the `as unknown as` erases all type checking -- a future Drizzle upgrade could break the PG instance's compatibility with the `BetterSQLite3Database` interface and TypeScript wouldn't catch it.
+
+### Approach: keep the cast, add compile-time compatibility check
+
+A wrapper class or union type was considered but rejected:
+- **Union type** would require narrowing at all ~250 db method call sites across 47 files
+- **Wrapper class** can't properly type the return values of `.select()`, `.insert()`, etc. because they return dialect-specific builder types, and the `.query` relational API is especially hard to wrap
+- **Runtime cost** of either alternative is zero -- this is purely a compile-time concern
+
+Instead, add a type-level assertion in `drizzle.ts` that verifies the PostgresJsDatabase type satisfies the key methods the codebase uses. This catches Drizzle upgrades that break structural compatibility at compile time.
+
+### Implementation
+
+Add a compile-time compatibility check after the type definitions in `drizzle.ts`:
+
+```ts
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+
+// Compile-time check: verify that PostgresJsDatabase exposes the same
+// core methods as BetterSQLite3Database.  If a Drizzle upgrade breaks
+// structural compatibility, this block will produce a type error.
+type _PgDB = PostgresJsDatabase<FullSchema>;
+type _AssertHas<T, K extends keyof T> = K;
+type _PgCheck =
+  | _AssertHas<_PgDB, "select">
+  | _AssertHas<_PgDB, "selectDistinct">
+  | _AssertHas<_PgDB, "insert">
+  | _AssertHas<_PgDB, "update">
+  | _AssertHas<_PgDB, "delete">
+  | _AssertHas<_PgDB, "query">
+  | _AssertHas<_PgDB, "transaction">
+  | _AssertHas<_PgDB, "$count">;
+// Suppress unused-type warning
+type _Unused = _PgCheck;
+```
+
+This is zero-cost at runtime (types are erased) and will fail `pnpm typecheck` if any of these methods are removed or renamed in a future Drizzle version.
+
+Also improve the existing TSDoc comment on the `db` export to explain the cast rationale and point to the compatibility check.
+
+### Files changed
+
+- `packages/db/drizzle.ts` -- add `PostgresJsDatabase` type import, add compile-time assertion block, improve TSDoc on `db` export
+
+## Verification
+
+- `pnpm typecheck` -- ensure no type errors from new assertions
+- `pnpm test` -- ensure existing tests pass (in-memory SQLite path unchanged)

.env.sample

@@ -1,3 +1,7 @@
 # See https://docs.karakeep.app/configuration for more information
 DATA_DIR=<path>
-NEXTAUTH_SECRET=<secret>
+NEXTAUTH_SECRET=<secret>
+
+# Database (optional, defaults to SQLite)
+# DATABASE_DIALECT=postgresql
+# DATABASE_URL=postgresql://user:password@host:5432/karakeep

.github/FUNDING.yml

@@ -1,4 +1,3 @@
 # These are supported funding model platforms
 
-buy_me_a_coffee: mbassem
-github: MohamedBassem
+github: johnford2002

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -33,7 +33,7 @@ body:
     attributes:
       label: Have you searched for an existing open/closed issue?
       description: |
-        To help us keep these issues under control, please ensure you have first [searched our issue list](https://github.com/karakeep-app/karakeep/issues?q=is%3Aissue) for any existing issues that cover the fundamental benefit/goal of your request.
+        To help us keep these issues under control, please ensure you have first [searched our issue list](https://github.com/johnford2002/karakeep/issues?q=is%3Aissue) for any existing issues that cover the fundamental benefit/goal of your request.
       options:
         - label: I have searched for existing issues and none cover my fundamental request
           required: true

.github/ISSUE_TEMPLATE/question.yml

@@ -5,4 +5,4 @@ body:
   - type: markdown
     attributes:
       value: |
-        We use Github discussions for anything that's not a bug report or a feature request. Please ask your question in the [Q&A section](https://github.com/karakeep-app/karakeep/discussions/categories/q-a) and someone will answer it soon!
+        We use Github discussions for anything that's not a bug report or a feature request. Please ask your question in the [Q&A section](https://github.com/johnford2002/karakeep/discussions/categories/q-a) and someone will answer it soon!

.github/workflows/fork-claude.yml

@@ -0,0 +1,61 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      github.actor == 'johnford2002' && (
+        (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+        (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+      )
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
+          # model: "claude-opus-4-20250514"
+
+          # Optional: Customize the trigger phrase (default: @claude)
+          # trigger_phrase: "/claude"
+
+          # Optional: Trigger when specific user is assigned to an issue
+          # assignee_trigger: "claude-bot"
+
+          # Optional: Allow Claude to run specific commands
+          allowed_tools: "Bash(pnpm install),Bash(pnpm typecheck),Bash(pnpm test),Bash(pnpm lint:fix)"
+
+          # Optional: Add custom instructions for Claude to customize its behavior for your project
+          # custom_instructions: |
+          #   Follow our coding standards
+          #   Ensure all new code has tests
+          #   Use TypeScript for new files
+
+          # Optional: Custom environment variables for Claude
+          # claude_env: |
+          #   NODE_ENV: test

.github/workflows/fork-docker.yml

@@ -0,0 +1,158 @@
+name: Build and Push Docker
+on:
+  release:
+    types:
+      - created
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [linux/amd64, linux/arm64]
+        image: [web, workers, cli, mcp, aio]
+        include:
+          - platform: linux/amd64
+            suffix: amd64
+            os: ubuntu-latest
+          - platform: linux/arm64
+            suffix: arm64
+            os: ubuntu-24.04-arm
+          - image: web
+            name: karakeep-web
+            target: web
+            image_name: ghcr.io/johnford2002/karakeep-web
+          - image: workers
+            name: karakeep-workers
+            target: workers
+            image_name: ghcr.io/johnford2002/karakeep-workers
+          - image: cli
+            name: karakeep-cli
+            target: cli
+            image_name: ghcr.io/johnford2002/karakeep-cli
+          - image: mcp
+            name: karakeep-mcp
+            target: mcp
+            image_name: ghcr.io/johnford2002/karakeep-mcp
+          - image: aio
+            name: karakeep-aio
+            target: aio
+            image_name: ghcr.io/johnford2002/karakeep
+    runs-on: ${{ matrix.os }}
+    permissions:
+      packages: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Github Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Prepare tags
+        id: tags
+        env:
+          IMAGE: ${{ matrix.image_name }}
+          SUFFIX: ${{ matrix.suffix }}
+          EVENT_NAME: ${{ github.event_name }}
+          RAW_VERSION: ${{ github.event.release.name }}
+        run: |
+          set -euo pipefail
+
+          # Strip leading 'v' so image tags follow docker convention (1.0.0, not v1.0.0)
+          VERSION="${RAW_VERSION#v}"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+          all_tags=""
+
+          if [[ "${EVENT_NAME}" == "push" ]]; then
+            all_tags="${IMAGE}:latest-${SUFFIX}"
+          fi
+
+          if [[ "${EVENT_NAME}" == "release" ]]; then
+            all_tags="${IMAGE}:${VERSION}-${SUFFIX},${IMAGE}:release-${SUFFIX}"
+          fi
+
+          echo "all=${all_tags}" >> "$GITHUB_OUTPUT"
+
+      - name: Build ${{ matrix.name }}
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          build-args: SERVER_VERSION=${{ github.event_name == 'release' && steps.tags.outputs.version || 'nightly' }}
+          file: docker/Dockerfile
+          target: ${{ matrix.target }}
+          platforms: ${{ matrix.platform }}
+          push: true
+          tags: ${{ steps.tags.outputs.all }}
+          cache-from: type=registry,ref=ghcr.io/johnford2002/karakeep-build-cache:${{ matrix.target }}-${{ matrix.suffix }}
+          cache-to: type=registry,mode=max,ref=ghcr.io/johnford2002/karakeep-build-cache:${{ matrix.target }}-${{ matrix.suffix }}
+
+  manifest:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: karakeep-web
+            image_name: ghcr.io/johnford2002/karakeep-web
+          - name: karakeep-workers
+            image_name: ghcr.io/johnford2002/karakeep-workers
+          - name: karakeep-cli
+            image_name: ghcr.io/johnford2002/karakeep-cli
+          - name: karakeep-mcp
+            image_name: ghcr.io/johnford2002/karakeep-mcp
+          - name: karakeep-aio
+            image_name: ghcr.io/johnford2002/karakeep
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Github Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create manifests for ${{ matrix.name }}
+        env:
+          IMAGE: ${{ matrix.image_name }}
+          IS_RELEASE: ${{ github.event_name == 'release' }}
+          IS_PUSH: ${{ github.event_name == 'push' }}
+          RAW_VERSION: ${{ github.event.release.name }}
+        run: |
+          set -euo pipefail
+
+          # Strip leading 'v' so image tags follow docker convention (1.0.0, not v1.0.0)
+          VERSION="${RAW_VERSION#v}"
+
+          create_manifest() {
+            local tag="$1"
+            docker buildx imagetools create \
+              -t "${tag}" \
+              "${tag}-amd64" \
+              "${tag}-arm64"
+          }
+
+          if [[ "${IS_PUSH}" == "true" ]]; then
+            create_manifest "${IMAGE}:latest"
+          fi
+
+          if [[ "${IS_RELEASE}" == "true" ]]; then
+            create_manifest "${IMAGE}:${VERSION}"
+            create_manifest "${IMAGE}:release"
+          fi

.github/workflows/android.yml → .github/workflows/upstream/android.yml

@@ -1,9 +1,8 @@
 name: Android App Release Build
-
+# Disabled in this fork. The upstream workflow publishes a karakeep-branded build.
+# Trigger manually via workflow_dispatch if you intend to produce your own build.
 on:
-  push:
-    tags:
-      - 'android/v[0-9]+.[0-9]+.[0-9]+-[0-9]+'
+  workflow_dispatch:
 
 jobs:
   build:

.github/workflows/cli.yml → .github/workflows/upstream/cli.yml

@@ -1,8 +1,7 @@
 name: Publish CLI Package to npm
+# Disabled in this fork to avoid conflicting with upstream @karakeep/cli on npm.
+# Trigger manually via workflow_dispatch if you publish your own package.
 on:
-  push:
-    tags:
-      - "cli/v[0-9]+.[0-9]+.[0-9]+"
   workflow_dispatch:
 
 permissions:

.github/workflows/extension.yml → .github/workflows/upstream/extension.yml

@@ -1,9 +1,8 @@
 name: Extension Release Build
-
+# Disabled in this fork. The upstream workflow publishes a karakeep-branded build.
+# Trigger manually via workflow_dispatch if you intend to produce your own build.
 on:
-  push:
-    tags:
-      - 'extension/v[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch:
 
 jobs:
   build:

.github/workflows/ios.yml → .github/workflows/upstream/ios.yml

@@ -1,9 +1,8 @@
 name: iOS App Release Build
-
+# Disabled in this fork. The upstream workflow publishes a karakeep-branded build.
+# Trigger manually via workflow_dispatch if you intend to produce your own build.
 on:
-  push:
-    tags:
-      - 'ios/v[0-9]+.[0-9]+.[0-9]+-[0-9]+'
+  workflow_dispatch:
 
 jobs:
   build:

.github/workflows/mcp.yml → .github/workflows/upstream/mcp.yml

@@ -1,9 +1,8 @@
 name: Publish MCP Package to npm
+# Disabled in this fork to avoid conflicting with the upstream MCP package on npm.
+# Trigger manually via workflow_dispatch if you publish your own package.
 on:
-  push:
-    tags:
-      # This is a glob pattern not a regex
-      - "mcp/v[0-9]+.[0-9]+.[0-9]+"
+  workflow_dispatch:
 
 permissions:
   id-token: write # Required for OIDC