feat(repos): pages with auto-revisions, refs with upsertByExternal

lib/db/repos/pages.js

@@ -0,0 +1,94 @@
+import { pool } from '../pool.js';
+import { recordAudit } from './audit_stub.js';
+
+async function snapshot(client, page_id, body_md, edited_by) {
+  await client.query(
+    `INSERT INTO page_revisions(page_id, body_md, edited_by)
+     VALUES($1,$2,$3)`,
+    [page_id, body_md, edited_by || null]
+  );
+}
+
+export async function create({ space_id, slug, title, body_md = '', parent_id }, actor) {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    const { rows: [r] } = await client.query(
+      `INSERT INTO pages(space_id, slug, title, body_md, parent_id)
+       VALUES($1,$2,$3,$4,$5) RETURNING *`,
+      [space_id, slug, title, body_md, parent_id || null]
+    );
+    await snapshot(client, r.id, body_md, actor?.kind);
+    await client.query('COMMIT');
+    await recordAudit(actor, 'create', 'page', r.id, null, r);
+    return r;
+  } catch (e) {
+    await client.query('ROLLBACK'); throw e;
+  } finally {
+    client.release();
+  }
+}
+
+export async function getById(id) {
+  const { rows: [r] } = await pool.query(`SELECT * FROM pages WHERE id=$1`, [id]);
+  return r;
+}
+
+export async function getBySlug(space_id, slug) {
+  const { rows: [r] } = await pool.query(
+    `SELECT * FROM pages WHERE space_id=$1 AND slug=$2`, [space_id, slug]
+  );
+  return r;
+}
+
+export async function listBySpace(space_id) {
+  const { rows } = await pool.query(
+    `SELECT id, space_id, slug, title, parent_id, updated_at
+     FROM pages WHERE space_id=$1 ORDER BY title`, [space_id]
+  );
+  return rows;
+}
+
+export async function listRevisions(page_id) {
+  const { rows } = await pool.query(
+    `SELECT * FROM page_revisions WHERE page_id=$1 ORDER BY created_at DESC`,
+    [page_id]
+  );
+  return rows;
+}
+
+export async function update(id, patch, actor) {
+  const before = await getById(id);
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    const fields = ['slug','title','body_md','body_html','parent_id','embedding'];
+    const sets = [], vals = [];
+    let i = 1;
+    for (const f of fields) {
+      if (patch[f] !== undefined) { sets.push(`${f}=$${i++}`); vals.push(patch[f]); }
+    }
+    sets.push(`updated_at=now()`);
+    vals.push(id);
+    const { rows: [r] } = await client.query(
+      `UPDATE pages SET ${sets.join(', ')} WHERE id=$${i} RETURNING *`,
+      vals
+    );
+    if (patch.body_md !== undefined && patch.body_md !== before.body_md) {
+      await snapshot(client, id, patch.body_md, actor?.kind);
+    }
+    await client.query('COMMIT');
+    await recordAudit(actor, 'update', 'page', id, before, r);
+    return r;
+  } catch (e) {
+    await client.query('ROLLBACK'); throw e;
+  } finally {
+    client.release();
+  }
+}
+
+export async function del(id, actor) {
+  const before = await getById(id);
+  await pool.query(`DELETE FROM pages WHERE id=$1`, [id]);
+  await recordAudit(actor, 'delete', 'page', id, before, null);
+}

lib/db/repos/refs.js

@@ -0,0 +1,82 @@
+import { pool } from '../pool.js';
+import { recordAudit } from './audit_stub.js';
+
+const FIELDS = [
+  'space_id','kind','source_url','title','description','summary',
+  'body_text','blob_path','thumbnail','metadata','embedding','status',
+  'source_kind','external_id','captured_at'
+];
+
+export async function create(input, actor) {
+  const cols = [], vals = [], placeholders = [];
+  let i = 1;
+  for (const f of FIELDS) {
+    if (input[f] !== undefined) {
+      cols.push(f); vals.push(input[f]); placeholders.push(`$${i++}`);
+    }
+  }
+  const { rows: [r] } = await pool.query(
+    `INSERT INTO refs(${cols.join(',')})
+     VALUES(${placeholders.join(',')}) RETURNING *`,
+    vals
+  );
+  await recordAudit(actor, 'create', 'ref', r.id, null, r);
+  return r;
+}
+
+export async function getById(id) {
+  const { rows: [r] } = await pool.query(`SELECT * FROM refs WHERE id=$1`, [id]);
+  return r;
+}
+
+export async function upsertByExternal(input, actor) {
+  const { source_kind, external_id } = input;
+  if (!source_kind || !external_id) {
+    throw new Error('upsertByExternal requires source_kind + external_id');
+  }
+  const { rows: [existing] } = await pool.query(
+    `SELECT * FROM refs WHERE source_kind=$1 AND external_id=$2`,
+    [source_kind, external_id]
+  );
+  if (existing) {
+    return update(existing.id, input, actor);
+  }
+  return create(input, actor);
+}
+
+export async function list({ space_id, kind, limit = 100, offset = 0 } = {}) {
+  const where = [], vals = [];
+  let i = 1;
+  if (space_id) { where.push(`space_id=$${i++}`); vals.push(space_id); }
+  if (kind) { where.push(`kind=$${i++}`); vals.push(kind); }
+  const w = where.length ? `WHERE ${where.join(' AND ')}` : '';
+  vals.push(limit, offset);
+  const { rows } = await pool.query(
+    `SELECT * FROM refs ${w} ORDER BY captured_at DESC LIMIT $${i++} OFFSET $${i}`,
+    vals
+  );
+  return rows;
+}
+
+export async function update(id, patch, actor) {
+  const before = await getById(id);
+  const sets = [], vals = [];
+  let i = 1;
+  for (const f of FIELDS) {
+    if (patch[f] !== undefined) { sets.push(`${f}=$${i++}`); vals.push(patch[f]); }
+  }
+  sets.push(`updated_at=now()`);
+  vals.push(id);
+  const { rows: [r] } = await pool.query(
+    `UPDATE refs SET ${sets.join(', ')} WHERE id=$${i} RETURNING *`,
+    vals
+  );
+  await recordAudit(actor, 'update', 'ref', id, before, r);
+  return r;
+}
+
+export async function del(id, actor) {
+  const before = await getById(id);
+  await pool.query(`DELETE FROM refs WHERE id=$1`, [id]);
+  await recordAudit(actor, 'delete', 'ref', id, before, null);
+}

tests/repos/pages.test.js

@@ -0,0 +1,33 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { resetDb } from '../helpers/db.js';
+import { migrateUp } from '../../lib/db/migrate.js';
+import * as spaces from '../../lib/db/repos/spaces.js';
+import * as pages from '../../lib/db/repos/pages.js';
+
+const owner = { kind: 'user', id: null };
+
+beforeEach(async () => { await resetDb(); await migrateUp(); });
+
+describe('pages repo', () => {
+  it('creates a page and auto-snapshots a revision', async () => {
+    const s = await spaces.create({ slug: 'h', name: 'H' }, owner);
+    const p = await pages.create(
+      { space_id: s.id, slug: 'a', title: 'A', body_md: 'hello' }, owner
+    );
+    expect(p.body_md).toBe('hello');
+    const revs = await pages.listRevisions(p.id);
+    expect(revs).toHaveLength(1);
+    expect(revs[0].body_md).toBe('hello');
+  });
+
+  it('updating body adds a revision', async () => {
+    const s = await spaces.create({ slug: 'h', name: 'H' }, owner);
+    const p = await pages.create(
+      { space_id: s.id, slug: 'a', title: 'A', body_md: 'v1' }, owner
+    );
+    await pages.update(p.id, { body_md: 'v2' }, owner);
+    const revs = await pages.listRevisions(p.id);
+    expect(revs).toHaveLength(2);
+    expect(revs[0].body_md).toBe('v2');  // newest first
+  });
+});

tests/repos/refs.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { resetDb } from '../helpers/db.js';
+import { migrateUp } from '../../lib/db/migrate.js';
+import * as spaces from '../../lib/db/repos/spaces.js';
+import * as refs from '../../lib/db/repos/refs.js';
+
+const owner = { kind: 'user', id: null };
+beforeEach(async () => { await resetDb(); await migrateUp(); });
+
+describe('refs repo', () => {
+  it('creates a url ref', async () => {
+    const s = await spaces.create({ slug: 'h', name: 'H' }, owner);
+    const r = await refs.create({
+      space_id: s.id, kind: 'url',
+      source_url: 'https://example.com',
+      title: 'Ex', source_kind: 'manual'
+    }, owner);
+    expect(r.kind).toBe('url');
+    expect(r.status).toBe('ingested');
+  });
+
+  it('idempotent upsert by (source_kind, external_id)', async () => {
+    const s = await spaces.create({ slug: 'h', name: 'H' }, owner);
+    const r1 = await refs.upsertByExternal({
+      space_id: s.id, kind: 'url', source_url: 'https://e.com',
+      source_kind: 'karakeep', external_id: 'kk-123', title: 'v1'
+    }, owner);
+    const r2 = await refs.upsertByExternal({
+      space_id: s.id, kind: 'url', source_url: 'https://e.com',
+      source_kind: 'karakeep', external_id: 'kk-123', title: 'v2'
+    }, owner);
+    expect(r2.id).toBe(r1.id);
+    expect(r2.title).toBe('v2');
+  });
+});