feat(enrichment): app migration framework + provider readiness + tmdb v4

Adds an app-data migration framework distinct from drizzle DDL migrations,
backfills enrichment refs for legacy recently rows, and computes provider
readiness server-side so the dashboard does not have to mirror gating logic.

* `_app_migrations` ledger table + `migrate:app` / `migrate:all` scripts
* `app-migrate.ts` runner uses the schema-distinct advisory lock and the
  full Nest DI graph; first migration backfills 21/92 legacy recently rows
* providers declare `featureGateConfigKey` + `requiredConfigKeys`;
  `getProviders()` returns `ready` / `missingKeys` so admin no longer has
  to read the (sanitized) `thirdPartyServiceIntegration` itself
* tmdb.client.ts switched to v4 Bearer auth (the dashboard hands out v4
  tokens by default; v3 query-param auth was silently 401-ing)

Author: Innei

apps/core/package.json

@@ -22,9 +22,11 @@
     "prebuild": "rimraf dist",
     "build": "npm run bundle",
     "dev": "npm run start",
-    "predev": "npm run migrate",
+    "predev": "npm run migrate:all",
     "dev:encrypt": "npm run start -- --encrypt_enable --encrypt_key=33b9405ac49f63ef4ccbf6b338aeeff8152e844d942ef22278abbec2b1f93b5e",
     "migrate": "tsx --env-file-if-exists=../../.env --tsconfig tsconfig.json src/migrate.ts",
+    "migrate:app": "cross-env NODE_ENV=development nest start --no-watch --entryFile app-migrate --path tsconfig.json",
+    "migrate:all": "npm run migrate && npm run migrate:app",
     "lint:migrations": "tsx --tsconfig tsconfig.json scripts/lint-migrations.ts",
     "repl": "npm run start -- --entryFile repl",
     "bundle": "tsdown",

apps/core/src/app-migrate.ts

@@ -0,0 +1,88 @@
+/**
+ * App-data migration runner.
+ *
+ * Boots a Nest application context (so migrations can `app.get(Service)` and
+ * use real DI graph), acquires a Postgres advisory lock distinct from the
+ * schema-migration lock, then iterates the registry in sorted id order. Each
+ * migration's `up()` is responsible for its own row-level idempotency; the
+ * runner only uses the `_app_migrations` ledger to skip work on re-runs.
+ *
+ * Schema migrations must run first — `migrate:all` chains the two binaries.
+ *
+ * Mirrors the import-order trick in `main.ts`: `initializeApp()` MUST run
+ * before AppModule (and anything in its graph) evaluates ambient globals
+ * such as `isDev`. ESM hoists static imports, so the AppModule import is
+ * deferred via dynamic `import()`.
+ */
+import 'dotenv-expand/config'
+
+import { Logger } from '@nestjs/common'
+import { NestFactory } from '@nestjs/core'
+import type pkg from 'pg'
+
+import { initializeApp } from './global/index.global'
+
+async function main() {
+  initializeApp()
+
+  const [
+    { AppModule },
+    { PG_DB_TOKEN, PG_POOL_TOKEN },
+    { migrations },
+    { appMigrations: ledgerTable },
+    { APP_MIGRATION_LOCK_KEY, withAdvisoryLock },
+  ] = await Promise.all([
+    import('./app.module'),
+    import('./constants/system.constant'),
+    import('./database/app-migrations/registry'),
+    import('./database/schema'),
+    import('./processors/database/postgres.lock'),
+  ])
+
+  const app = await NestFactory.createApplicationContext(
+    AppModule.register(false),
+    {
+      logger: ['error', 'warn', 'log'],
+    },
+  )
+  const logger = new Logger('app-migrate')
+  const db = app.get(
+    PG_DB_TOKEN,
+  ) as import('./processors/database/postgres.provider').AppDatabase
+  const pool = app.get<pkg.Pool>(PG_POOL_TOKEN)
+
+  try {
+    await withAdvisoryLock(pool, APP_MIGRATION_LOCK_KEY, async () => {
+      const appliedRows = await db
+        .select({ id: ledgerTable.id })
+        .from(ledgerTable)
+      const applied = new Set(appliedRows.map((r) => r.id))
+
+      const sorted = [...migrations].sort((a, b) => a.id.localeCompare(b.id))
+      for (const m of sorted) {
+        if (applied.has(m.id)) {
+          logger.log(`⊘ ${m.id} (already applied)`)
+          continue
+        }
+        logger.log(`▶ ${m.id} — ${m.description}`)
+        const start = Date.now()
+        try {
+          await m.up({ app, logger })
+          const ms = Date.now() - start
+          await db.insert(ledgerTable).values({ id: m.id, durationMs: ms })
+          logger.log(`✓ ${m.id} (${ms}ms)`)
+        } catch (err) {
+          logger.error(`✗ ${m.id}`, err as Error)
+          throw err
+        }
+      }
+    })
+  } finally {
+    await app.close()
+  }
+}
+
+main().catch((err) => {
+  console.error('[app-migrate] failed:', err)
+  process.exit(1)
+})

apps/core/src/database/app-migrations/20260506-enrichment-backfill.ts

@@ -0,0 +1,62 @@
+import { EnrichmentService } from '~/modules/enrichment/enrichment.service'
+import { RecentlyRepository } from '~/modules/recently/recently.repository'
+
+import type { AppMigration } from './types'
+
+const URL_REGEX = /https?:\/\/\S+/i
+// Strip trailing punctuation that the regex greedily includes; the CJK set
+// matches the same trim used by the Yohaku post-box auto-detect.
+const URL_TAIL_TRIM = /[!"'),.:;>?\]`}—…、。〉《》「」『』〕！），：；？]+$/
+
+export function extractFirstUrl(
+  content: string | null | undefined,
+): string | null {
+  if (!content) return null
+  const m = content.match(URL_REGEX)
+  if (!m) return null
+  let url = m[0]
+  while (URL_TAIL_TRIM.test(url)) url = url.replace(URL_TAIL_TRIM, '')
+  return url || null
+}
+
+export const migration: AppMigration = {
+  id: '20260506-enrichment-backfill',
+  description: 'Backfill enrichment refs for legacy recently rows',
+  async up({ app, logger }) {
+    const enrichmentService = app.get(EnrichmentService)
+    const recentlyRepo = app.get(RecentlyRepository)
+
+    const rows = await recentlyRepo.findWithoutEnrichment()
+    let matched = 0
+    let skipped = 0
+    let resolveFailed = 0
+    for (const row of rows) {
+      const url =
+        (row.metadata as { url?: string } | null)?.url ??
+        extractFirstUrl(row.content)
+      if (!url) {
+        skipped++
+        continue
+      }
+      const ref = enrichmentService.matchUrlToRef(url)
+      if (!ref) {
+        skipped++
+        continue
+      }
+      await recentlyRepo.update(row.id, {
+        enrichmentProvider: ref.provider,
+        enrichmentExternalId: ref.externalId,
+      })
+      try {
+        await enrichmentService.resolve(url)
+      } catch (err) {
+        resolveFailed++
+        logger.warn(`resolve failed for ${url}: ${(err as Error).message}`)
+      }
+      matched++
+    }
+    logger.log(
+      `backfill: total=${rows.length} matched=${matched} skipped=${skipped} resolveFailed=${resolveFailed}`,
+    )
+  },
+}

apps/core/src/database/app-migrations/registry.ts

@@ -0,0 +1,9 @@
+import { migration as enrichmentBackfill } from './20260506-enrichment-backfill'
+import type { AppMigration } from './types'
+
+/**
+ * Ordered list of app-data migrations. Runner sorts by id (lexicographic on
+ * the `YYYYMMDD-slug` prefix) before iterating, so insertion order here is
+ * not load-bearing — adding a new migration is just `import + push`.
+ */
+export const migrations: AppMigration[] = [enrichmentBackfill]

apps/core/src/database/app-migrations/types.ts

@@ -0,0 +1,18 @@
+import type { INestApplicationContext, Logger } from '@nestjs/common'
+
+/**
+ * App-data migration: a one-time runtime transform applied against an already
+ * migrated schema. Distinct from drizzle-kit DDL migrations.
+ *
+ * `up` runs inside a Postgres advisory lock, so concurrent runners will not
+ * race. Each implementation MUST be idempotent: a re-run after partial
+ * failure or a second instance starting before the ledger row was written
+ * must produce the same end state. Runner-level guard is the ledger; the
+ * row-level guard is the migration's responsibility.
+ */
+export interface AppMigration {
+  /** Stable id, `YYYYMMDD-slug`. Used as ledger primary key. */
+  id: string
+  description: string
+  up: (ctx: { app: INestApplicationContext; logger: Logger }) => Promise<void>
+}

apps/core/src/database/migrations/0005_app_migrations_ledger.sql

@@ -0,0 +1,5 @@
+CREATE TABLE "_app_migrations" (
+	"id" text PRIMARY KEY NOT NULL,
+	"applied_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"duration_ms" integer
+);