Reference index: the amal66 fork, decomposed into 25 reviewable PRs

.dockerignore

@@ -0,0 +1,25 @@
+node_modules
+*/node_modules
+**/node_modules
+
+# Build artifacts
+apps/api/dist
+apps/web/.next
+apps/web/out
+
+# Development files that should not leak into images
+.env
+**/.env
+.env.local
+**/.env.local
+
+# VCS and editor noise
+.git
+.gitignore
+.github
+*.md
+!apps/api/.env.example
+
+# Test outputs
+coverage
+.nyc_output

.github/CODEOWNERS

@@ -0,0 +1,31 @@
+# CODEOWNERS — automatic reviewer assignment
+#
+# HOW THIS WORKS:
+# When a pull request touches a file matched by a pattern below, GitHub
+# automatically adds the listed user(s) as required reviewers.  The PR
+# cannot be merged until the CODEOWNER approves it.
+#
+# This is especially valuable for security-sensitive files: if someone
+# submits a PR that modifies the auth middleware, you want a security-
+# aware reviewer automatically in the loop — not relying on a reviewer
+# happening to notice which files changed.
+#
+# SYNTAX: <pattern>  <@user or @org/team>
+# Patterns follow .gitignore rules. The LAST matching rule wins.
+
+# Default owner for everything
+*                                   @amal66
+
+# Security-sensitive backend files — always need a careful review
+apps/api/src/middleware/auth.ts     @amal66
+apps/api/src/lib/env.ts             @amal66
+apps/api/src/lib/userApiKeys.ts     @amal66
+apps/api/src/core/downloadTokens.ts @amal66
+apps/api/src/lib/access.ts          @amal66
+
+# Database migrations — irreversible in production, need careful sign-off
+supabase/migrations/                @amal66
+
+# CI/CD pipelines — changes here can break deployments or weaken security
+.github/workflows/                  @amal66
+.github/CODEOWNERS                  @amal66

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,17 @@
+---
+name: Bug report
+about: Report a reproducible problem
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+## Steps To Reproduce
+
+## Expected Behavior
+
+## Actual Behavior
+
+## Environment

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Suggest an improvement
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+## Proposal
+
+## Alternatives
+
+## Additional Context

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,30 @@
+## Summary
+
+<!-- What does this PR do, in one or two sentences? -->
+
+## Why / Motivation
+
+<!-- What problem does this solve? Why now, and why this approach?
+     Link the issue or context that prompted it. -->
+
+## Changes
+
+<!-- The notable changes, at a high level. Describe the outcome, not the diff. -->
+
+## Tradeoffs & risks
+
+<!-- What did you weigh? What could break, what's out of scope, and what
+     follow-ups (if any) does this leave behind? Note any security or
+     migration implications. -->
+
+## How verified
+
+<!-- How do you know this works? Tests added/run, manual steps, commands,
+     screenshots. Include the exact commands where relevant. -->
+
+## Checklist
+
+- [ ] Ran the relevant build/test command for the area changed.
+- [ ] Reviewed `git diff` and removed unrelated changes.
+- [ ] Updated docs / env examples if setup, config, or behavior changed.
+- [ ] No secrets, API keys, real documents, or `.env` files committed.

.github/dependabot.yml

@@ -0,0 +1,67 @@
+# Dependabot automatically opens PRs to keep dependencies up to date.
+#
+# WHY DEPENDABOT MATTERS:
+# The Node.js ecosystem has thousands of transitive dependencies.  A
+# vulnerability found in a package you've never heard of (e.g. a nested
+# transitive dep of express) becomes your problem if it's exploitable in
+# your context.
+#
+# Dependabot monitors the GitHub Advisory Database and opens a PR within
+# hours of a new CVE being published.  Without it, you'd find out about
+# a vulnerability when a security researcher reports it against YOUR app.
+#
+# HOW IT WORKS:
+# Every day (for security alerts) or weekly (for version bumps), Dependabot
+# reads your package-lock.json and checks whether any installed version has
+# a known CVE.  If so, it opens a PR that bumps the affected package to the
+# patched version.
+#
+# You still review and merge the PR — Dependabot never pushes directly.
+# CI runs on the PR so you can see if the update breaks anything before
+# merging.
+
+version: 2
+updates:
+  # Root workspace / monorepo tooling
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    groups:
+      # Group all minor/patch dev-dep bumps into one PR per week
+      dev-dependencies:
+        dependency-type: "development"
+        update-types: ["minor", "patch"]
+
+  # API workspace
+  - package-ecosystem: "npm"
+    directory: "/apps/api"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    groups:
+      dev-dependencies:
+        dependency-type: "development"
+        update-types: ["minor", "patch"]
+
+  # Web workspace
+  - package-ecosystem: "npm"
+    directory: "/apps/web"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    groups:
+      dev-dependencies:
+        dependency-type: "development"
+        update-types: ["minor", "patch"]
+
+  # GitHub Actions version pinning
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"

.github/workflows/ci.yml

@@ -0,0 +1,193 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  api:
+    name: API tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/api
+    env:
+      # Dummy values so env.ts validation passes at test time
+      SUPABASE_URL: http://localhost:54321
+      SUPABASE_SECRET_KEY: test-secret-key
+      # env.ts enforces a >=32-char minimum on these; keep the dummies above it
+      # so the test suite AND the built-app smoke import both pass env validation.
+      DOWNLOAD_SIGNING_SECRET: ci-download-signing-secret-32bytes-min!
+      USER_API_KEYS_ENCRYPTION_SECRET: ci-user-api-keys-encryption-secret-32bytes-min!
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - run: npm ci
+        working-directory: .
+
+      # Fail the build if any high or critical CVEs exist in dependencies.
+      # `--audit-level=high` means: pass if only low/moderate vulns exist,
+      # fail if any high or critical ones do.
+      # Why not --audit-level=critical? High CVEs are often exploitable too
+      # and should not be silently ignored.
+      - name: Dependency security audit
+        run: npm audit --audit-level=high
+        working-directory: apps/api
+
+      - run: npm run lint
+      # Run with coverage so the no-regression thresholds in vitest.config.mts
+      # are enforced in CI (fails the build if lib coverage drops).
+      - run: npm run test:coverage
+      - run: npm run build
+      - name: Smoke import built API app
+        run: node -e "require('./dist/apps/api/src/app.js'); console.log('api app import ok')"
+
+  packages:
+    name: Package typecheck and tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - run: npm ci
+        working-directory: .
+
+      - run: ./node_modules/.bin/tsc -p packages/core/tsconfig.json --noEmit
+      - run: ./node_modules/.bin/tsc -p packages/api-client/tsconfig.json --noEmit
+      - run: ./node_modules/.bin/tsc -p packages/sdk-js/tsconfig.json --noEmit
+      # packages/shared is consumed as raw TSX by apps/web (transpilePackages)
+      # and word-addin (webpack alias), so neither consumer typechecks it as a
+      # unit — this is the only gate that does.
+      - run: ./node_modules/.bin/tsc -p packages/shared/tsconfig.json --noEmit
+      # Run the package test suites, not just the compiler: api-client pins the
+      # server→client field remapping and sdk-js pins the public SDK surface.
+      # Typechecking alone would miss a behavioral regression in either.
+      - run: npm test --workspace packages/api-client
+      - run: npm test --workspace packages/sdk-js
+
+  # -----------------------------------------------------------------------
+  # Offline eval harness: deterministic scorecard for citation accuracy,
+  # prompt-injection resistance, and privilege/PII leakage. Runs against
+  # committed fixtures (no network, no LLM calls, no secrets), so it is cheap
+  # enough to gate every PR. --threshold 1.0 = every case must pass.
+  # -----------------------------------------------------------------------
+  evals:
+    name: Eval harness
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - run: node evals/run.mjs --threshold 1.0
+
+  # -----------------------------------------------------------------------
+  # Python SDK: installed and tested on the oldest supported Python (3.9,
+  # per pyproject requires-python) so compatibility claims stay honest.
+  # Tests are offline (respx-mocked httpx), so no secrets are needed.
+  # -----------------------------------------------------------------------
+  python-sdk:
+    name: Python SDK tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sdks/python
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+
+      - run: pip install -e .[dev]
+      - run: python -m pytest
+
+  web:
+    name: Web lint and build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/web
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - run: npm ci
+        working-directory: .
+      # `npm ci` intermittently skips lightningcss's platform-native optional
+      # dependency on Linux (npm/cli#4828), which breaks `next build` with
+      # "Cannot find module '../lightningcss.linux-x64-gnu.node'". Reinstalling
+      # lightningcss (without touching the lockfile) fetches the runner's
+      # matching native binary.
+      - run: npm install --no-save lightningcss
+        working-directory: .
+      - run: npm run lint
+      # Coverage mode so the no-regression thresholds in vitest.config.mts are
+      # enforced (same ratchet pattern as apps/api).
+      - run: npm run test:coverage
+      - run: npm run build
+
+  # -----------------------------------------------------------------------
+  # Slower job: migration validation against real local Supabase (3-5 min)
+  # Runs on PRs and pushes. Supabase's local stack applies the migrations
+  # against a real Postgres/Auth environment, which catches SQL drift that
+  # mocked unit tests cannot see.
+  # -----------------------------------------------------------------------
+  migrations:
+    name: Migration validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: supabase/setup-cli@v2
+        with:
+          version: latest
+
+      - name: Start Supabase
+        run: supabase start
+
+      - name: Reset DB (applies all migrations from scratch)
+        run: supabase db reset
+
+      - name: Stop Supabase
+        run: supabase stop --no-backup
+
+  # -----------------------------------------------------------------------
+  # Deploy job: push migrations to production on merge to main
+  # -----------------------------------------------------------------------
+  deploy-migrations:
+    name: Deploy migrations
+    runs-on: ubuntu-latest
+    needs: [api, packages, web, migrations, evals, python-sdk]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: supabase/setup-cli@v2
+        with:
+          version: latest
+
+      - name: Push migrations to production
+        run: supabase db push --db-url "${{ secrets.DATABASE_URL }}"
+        env:
+          SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}