feat: Transcribe auth

.env.example

@@ -14,4 +14,7 @@ NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
 NEXT_PUBLIC_GITHUB_REPO=undead404/koreni
 NEXT_PUBLIC_GISCUS_REPO_ID=
 NEXT_PUBLIC_GISCUS_CATEGORY_ID=
-GEMINI_API_KEY=
+GEMINI_API_KEY=
+NEXT_PUBLIC_OAUTH_CLIENT_ID=
+OAUTH_CLIENT_SECRET=
+NEXT_PUBLIC_API_SITE=http://localhost:4000

.github/workflows/check-pr.yml

@@ -27,6 +27,12 @@ jobs:
         run: yarn --frozen-lockfile --prefer-offline
         working-directory: src/server
 
+      - name: Generate Kysely types
+        run: yarn exec kysely-codegen --dialect libsql
+        working-directory: src/server
+        env:
+          DATABASE_URL: '${{ vars.TURSO_DATABASE_URL }}?authToken=${{ secrets.TURSO_DATABASE_TOKEN }}'
+
       - name: Lint
         run: yarn lint
 

.github/workflows/main.yml

@@ -258,8 +258,6 @@ jobs:
             echo "NEXT_PUBLIC_SITE=${{ vars.SITE }}" >> .env
             echo "NODE_ENV=production" >> .env
             echo "VALID_API_KEYS=${{ vars.VALID_API_KEYS }}" >> .env
-            echo "GITHUB_OAUTH_CLIENT_ID=${{ secrets.OAUTH_CLIENT_ID }}" >> .env
-            echo "GITHUB_OAUTH_CLIENT_SECRET=${{ secrets.OAUTH_CLIENT_SECRET }}" >> .env
             echo "FALLBACK_EMAIL=${{ secrets.FALLBACK_EMAIL }}" >> .env
 
             # Install dependencies ON THE SERVER

.gitignore

@@ -56,4 +56,6 @@ next-env.d.ts
 .gemini/
 
 # GitHub App credentials
-gha-creds-*.json
+gha-creds-*.json
+
+/src/server/local.db

README.md

@@ -18,18 +18,40 @@ All other contents (the code and everything else) in this repository is licensed
 2. Yarn
 3. Docker
 
-The easiest way is to setup Typesense with Docker. Run this:
-
 ```sh
 yarn
-yarn docker:typesense:start
+yarn docker:typesense:start # If you want to use TypeSense search
 yarn typesense:populate # This takes substantial time
+cd ./src/server && yarn db:init && cd ../..
+cp ./.env.example ./.env
+cp ./src/server/.env.example ./src/server/.env
+```
+
+In `./src/server/.env`, you need to set a strong JWT_SECRET value. To generate it, you can use this command:
+
+```sh
+# Source - https://stackoverflow.com/a/74481179
+# Retrieved 2026-05-30, License - CC BY-SA 4.0
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'));"
+```
+
+To set `NEXT_PUBLIC_OAUTH_CLIENT_ID` in `./.env` and `OAUTH_CLIENT_ID` in `./src/server/.env`, ask the maintainer - @undead404.
+
+Then, to run the app:
+
+```sh
 yarn dev
 ```
 
+If you want to work with data contribution and-or transcription, run in another terminal:
+
+```sh
+yarn dev:server
+```
+
 ## Production setup
 
-Use scripts from scripts/prepare-server folder.
+Use scripts from `./scripts/prepare-server` folder.
 
 ## Clean repo
 

package.json

@@ -4,6 +4,7 @@
     "@bugsnag/plugin-react": "^8.2.0",
     "@hookform/error-message": "^2.0.1",
     "@hookform/resolvers": "^5.2.2",
+    "@react-oauth/google": "^0.13.5",
     "clsx": "^2.1.1",
     "dotenv": "~16.4.7",
     "leaflet": "~1.9.4",

specs/039-project-create.md

@@ -0,0 +1,43 @@
+# Project create
+
+## Pathname
+
+Create a new component at `src/app/transcribe/create`.
+
+## UX
+
+Add form to create a new project.
+
+The required schema is defined in `src/server/src/schemata.ts` – `projectCreatePayloadSchema`.
+
+Fields:
+
+- Title: text input, required
+- ID: text input, required, unique across all projects
+- isHandwritten: select (unset, handwritten, typed), required
+- Location: coordinates of the settlement relevant to the project, required. May copy `src/app/components/contribute/spatial-input.tsx`
+- Sources: URLs relevant to the project, required. May copy `src/app/components/contribute/sources-input.tsx`
+- Table locale: select (unset, pl, ru, uk), required
+- Years range: range of years relevant to the project, or a single year, required. May copy `src/app/components/contribute/years-input.tsx`
+
+## Request
+
+Send a POST request to `new URL('/api/transcribe/projects', environment.NEXT_PUBLIC_API_SITE)`.
+
+### Request body
+
+```http
+POST /api/transcribe/projects HTTP/1.1
+Host: localhost:4000
+Content-Type: application/json
+
+{
+  "id": "test",
+  "isHandwritten": true,
+  "location": [0, 0],
+  "sources": ["https://example/com/data"],
+  "tableLocale": "pl",
+  "title": "Test",
+  "yearsRange": [1900, 2000]
+}
+```

specs/040-project-create-link.md

@@ -0,0 +1,3 @@
+# Project create link
+
+Add a link to the project creation page (`/transcribe/create`) at `src/app/transcribe/page.tsx`, above the projects list.

specs/041-project-create-crash.md

@@ -0,0 +1,8 @@
+# Project create crash
+
+## Error text
+
+```plain
+TypeError: Cannot read properties of undefined (reading 'join')
+    at Object.render (page.tsx:164:38)
+```

specs/068-local-sqlite-fallback.md

@@ -0,0 +1,118 @@
+---
+description: Update database configuration to support local SQLite fallback for development without Turso credentials.
+status: draft
+targets:
+  - src/server/src/database/client.ts
+  - src/server/.env.example
+  - src/server/src/environment.ts
+  - src/server/package.json
+  - src/server/src/database/init.ts
+context:
+  - src/server/src/database/schema.sql
+---
+
+# Local SQLite Fallback for Development
+
+## 1. Architectural Boundary
+
+- **Execution Context:** Server (Hono)
+- **Data Scope:** SQLite (Kysely)
+
+---
+
+## 2. State Transition Matrix
+
+### Fault / Current State
+
+- **Condition:** A new developer clones the repository and attempts to start the backend locally.
+- **Behavior:** The application crashes during environment variable validation because `TURSO_DATABASE_URL` is enforced as a URL and `TURSO_DATABASE_TOKEN` is a mandatory non-empty string.
+- **Log/Trace:**
+
+```ts
+ZodError: [
+  {
+    code: 'invalid_type',
+    expected: 'string',
+    received: 'undefined',
+    path: ['TURSO_DATABASE_URL'],
+    message: 'Required',
+  },
+  {
+    code: 'custom',
+    message: 'String cannot be empty',
+    path: ['TURSO_DATABASE_TOKEN'],
+  },
+];
+```
+
+### Target / Resolved State
+
+- **Condition:** A new developer starts the application locally with an empty `.env` or defaults from `.env.example`.
+- **Behavior:** The application falls back to a local SQLite database file (e.g., `file:local.db`) and bypasses the requirement for a Turso authentication token. The developer can initialize the local database schema using a new `db:init` script.
+- **Schema/Type Alteration:**
+
+```ts
+const environmentSchema = z.object({
+  // ...
+  TURSO_DATABASE_URL: z.string().default('file:local.db'),
+  TURSO_DATABASE_TOKEN: nonEmptyString.optional(),
+});
+```
+
+---
+
+## 3. Execution Pipeline
+
+### 3.1. src/server/src/environment.ts
+
+1. Modify the `TURSO_DATABASE_URL` validation in `environmentSchema` to support local file connections (e.g., `z.string()`) and provide a default value of `'file:local.db'`.
+2. Update `TURSO_DATABASE_TOKEN` to be optional using `.optional()`.
+
+### 3.2. src/server/.env.example
+
+1. Update the example configuration to indicate that `TURSO_DATABASE_URL` and `TURSO_DATABASE_TOKEN` can be omitted for local development to use a local SQLite instance.
+
+### 3.3. src/server/src/database/client.ts
+
+1. Update the `createClient` configuration object to safely pass `environment.TURSO_DATABASE_TOKEN` only if it is defined, preventing validation errors from `@libsql/client` when running without a remote auth token.
+
+### 3.4. src/server/package.json
+
+1. Add a `"db:init"` script (e.g., `"db:init": "tsx src/database/init.ts"`) that developers can run to seed the local SQLite database file with the correct initial schema structure after cloning the project.
+
+### 3.5. src/server/src/database/init.ts
+
+1. Create a script that utilizes the existing `better-sqlite3` and `fs` packages.
+2. The script should read the contents of `src/server/src/database/schema.sql`.
+3. It should instantiate a new `Database('local.db')` and execute the SQL schema string to initialize the database structure.
+
+---
+
+## 4. Hard Constraints
+
+- **Backend ESM:** All relative imports in Hono/Node.js files MUST terminate with explicit `.js` extensions.
+- **Isolation:** Do not modify schemas, context files, or unrelated components not explicitly listed in the `targets` frontmatter.
+
+---
+
+## 5. Agentic Verification
+
+Execute the following commands to validate the implementation:
+
+1. **Type & Lint Pass:** Run standard formatting and type checks.
+
+```opencode
+   /lint
+```
+
+2. **Targeted Test Execution:** Run the specific route or backend test.
+
+```opencode
+   /test-server
+```
+
+3. **ESM Validation (Backend Only):**
+
+```opencode
+   /verify-esm src/server/src/database/client.ts
+```

src/app/components/contribute/location-picker.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import type { Marker as LMarker } from 'leaflet';
 import { usePostHog } from 'posthog-js/react';
 import { memo, useMemo, useRef } from 'react';

src/app/environment.ts

@@ -33,6 +33,11 @@ const environment = {
     process.env.NEXT_PUBLIC_LOCATIONIQ_KEY,
     false,
   ),
+  NEXT_PUBLIC_OAUTH_CLIENT_ID: validateEnvironment(
+    'NEXT_PUBLIC_OAUTH_CLIENT_ID',
+    process.env.NEXT_PUBLIC_OAUTH_CLIENT_ID,
+    true,
+  ),
   NEXT_PUBLIC_POSTHOG_KEY: validateEnvironment(
     'NEXT_PUBLIC_POSTHOG_KEY',
     process.env.NEXT_PUBLIC_POSTHOG_KEY,

src/app/helpers/generate-metadata.ts

@@ -238,7 +238,7 @@ export function generateJsonLd(item: IndexationTable): string {
     ],
   };
 
-  return process.env.NODE_ENV === 'development'
+  return environment.NODE_ENV === 'development'
     ? JSON.stringify(jsonLd, null, 2)
     : JSON.stringify(jsonLd);
 }

src/app/transcribe/components/logout-button.module.css

@@ -0,0 +1,17 @@
+.root {
+  display: inline-flex;
+  padding: 0.25rem 0.5rem;
+  background-color: #dc2626;
+  color: #fff;
+  border-radius: 0.25rem;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 500;
+  text-decoration: none;
+  cursor: pointer;
+  user-select: none;
+  transition:
+    background-color 0.2s ease-in-out,
+    border-color 0.2s ease-in-out,
+    color 0.2s ease-in-out;
+}

src/app/transcribe/components/logout-button.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { googleLogout } from '@react-oauth/google';
+import { useRouter } from 'next/navigation';
+import { toast } from 'sonner';
+
+import requestApi from '../services/api';
+
+import styles from './logout-button.module.css';
+
+export default function LogoutButton() {
+  const router = useRouter();
+
+  const handleLogout = () => {
+    // 1. Sever the local Google Identity SDK state
+    googleLogout();
+
+    // 2. Execute backend cookie destruction
+    requestApi('/api/auth/session/current', {
+      method: 'DELETE',
+    })
+      .then(() => {
+        router.push('/transcribe/login');
+        return;
+      })
+      .catch(() => {
+        toast.error('Failed to log out');
+      });
+  };
+
+  return (
+    <button onClick={handleLogout} className={styles.root}>
+      Log Out
+    </button>
+  );
+}

src/app/transcribe/components/projects-list.tsx

@@ -0,0 +1,32 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { toast } from 'sonner';
+
+import { type Project, projectResponseSchema } from '../schemata';
+import requestApi from '../services/api';
+
+export default function ProjectsList() {
+  const [projects, setProjects] = useState<Project[]>([]);
+  useEffect(() => {
+    requestApi('/api/transcribe/projects')
+      .then((response) => response.json())
+      .then((data: unknown) => {
+        const projectsData = projectResponseSchema.parse(data);
+        setProjects(projectsData.projects);
+        return;
+      })
+      .catch(() => {
+        toast.error('Error loading projects');
+      });
+  }, []);
+  return (
+    <section>
+      <h1>Projects</h1>
+      {projects.map((project) => (
+        <p key={project.id}>{project.title}</p>
+      ))}
+      {projects.length === 0 && <p>No projects</p>}
+    </section>
+  );
+}

src/app/transcribe/components/transcribe-header.module.css

@@ -0,0 +1,8 @@
+.root {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 0 1rem;
+  background-color: #fff;
+  border-bottom: 1px solid #e5e7eb;
+}