feat(api): source-docs routes

Add lib/api/routes/source_docs.js: scoped POST under a resource,
get/patch/delete by id, and POST /:id/resync as a Plan 3 stub gated
by ENABLE_RESYNC (503 by default, 202 once workers ship). upstream_url
is required by the DB so the zod schema enforces it.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

lib/api/index.js

@@ -11,6 +11,7 @@ import {
 import { router as pagesRouter, spacesScopedRouter as pagesBySpaceRouter } from './routes/pages.js';
 import { router as refsRouter } from './routes/refs.js';
 import { router as resourcesRouter, spacesScopedRouter as resourcesBySpaceRouter } from './routes/resources.js';
+import { router as sourceDocsRouter, resourcesScopedRouter as sourceDocsByResourceRouter } from './routes/source_docs.js';
 
 export function mountApi(app) {
   const api = Router();
@@ -27,6 +28,8 @@ export function mountApi(app) {
   api.use('/pages', pagesRouter);
   api.use('/refs', refsRouter);
   api.use('/resources', resourcesRouter);
+  api.use('/resources/:resource_id/source-docs', sourceDocsByResourceRouter);
+  api.use('/source-docs', sourceDocsRouter);
 
   api.use((_req, _res, next) => next(new NotFoundError('route not found')));
 

lib/api/routes/source_docs.js

@@ -0,0 +1,88 @@
+import { Router } from 'express';
+import { z } from 'zod';
+import * as repo from '../../db/repos/source_docs.js';
+import { validate } from '../validate.js';
+import { NotFoundError, ValidationError, asyncWrap } from '../errors.js';
+
+const baseFields = {
+  name: z.string().min(1).max(200),
+  upstream_url: z.string().min(1).max(2048),
+  version: z.string().nullable().optional(),
+  format: z.string().nullable().optional(),
+  sync_source: z.string().nullable().optional(),
+  local_path: z.string().nullable().optional(),
+  body_text: z.string().nullable().optional(),
+  last_synced: z.string().datetime().nullable().optional(),
+  metadata: z.record(z.string(), z.any()).nullable().optional()
+};
+
+const createSchema = z.object(baseFields);
+const patchSchema = z.object(Object.fromEntries(
+  Object.entries(baseFields).map(([k, v]) => [k, v.optional()])
+));
+
+const idParams = z.object({ id: z.string().uuid() });
+const resourceParams = z.object({ resource_id: z.string().uuid() });
+
+export const router = Router();
+export const resourcesScopedRouter = Router({ mergeParams: true });
+
+resourcesScopedRouter.post('/',
+  validate({ params: resourceParams, body: createSchema }),
+  asyncWrap(async (req, res) => {
+    try {
+      const row = await repo.create({ ...req.body, resource_id: req.params.resource_id }, req.actor);
+      res.status(201).json(row);
+    } catch (e) {
+      if (e.code === '23503') throw new ValidationError('invalid resource', {
+        resource_id: req.params.resource_id
+      });
+      throw e;
+    }
+  })
+);
+
+router.get('/:id',
+  validate({ params: idParams }),
+  asyncWrap(async (req, res) => {
+    const row = await repo.getById(req.params.id);
+    if (!row) throw new NotFoundError('source doc not found');
+    res.json(row);
+  })
+);
+
+router.patch('/:id',
+  validate({ params: idParams, body: patchSchema }),
+  asyncWrap(async (req, res) => {
+    const existing = await repo.getById(req.params.id);
+    if (!existing) throw new NotFoundError('source doc not found');
+    res.json(await repo.update(req.params.id, req.body, req.actor));
+  })
+);
+
+router.delete('/:id',
+  validate({ params: idParams }),
+  asyncWrap(async (req, res) => {
+    const existing = await repo.getById(req.params.id);
+    if (!existing) throw new NotFoundError('source doc not found');
+    await repo.del(req.params.id, req.actor);
+    res.status(204).end();
+  })
+);
+
+// Resync hooks into the pg-boss worker queue in Plan 3. Gated behind
+// ENABLE_RESYNC so the route exists for the UI but doesn't enqueue
+// jobs that have no consumer yet.
+router.post('/:id/resync',
+  validate({ params: idParams }),
+  asyncWrap(async (req, res) => {
+    const existing = await repo.getById(req.params.id);
+    if (!existing) throw new NotFoundError('source doc not found');
+    if (process.env.ENABLE_RESYNC !== 'true') {
+      return res.status(503).json({
+        error: { code: 'feature_disabled', message: 'resync workers land in Plan 3' }
+      });
+    }
+    res.status(202).json({ queued: true, note: 'workers land in Plan 3' });
+  })
+);

tests/api/source_docs.test.js

@@ -0,0 +1,59 @@
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import request from 'supertest';
+import { setup } from './helpers.js';
+import * as spaces from '../../lib/db/repos/spaces.js';
+import * as resources from '../../lib/db/repos/resources.js';
+
+let app, ownerHeaders, resource;
+const owner = { kind: 'user', id: null };
+
+beforeAll(async () => { ({ app, ownerHeaders } = await setup()); });
+beforeEach(async () => {
+  const space = await spaces.create({ slug: `s-${Date.now()}-${Math.random().toString(36).slice(2,5)}`, name: 'S' }, owner);
+  resource = await resources.create({
+    space_id: space.id, slug: 'svc', name: 'svc', runtime_type: 'lxc'
+  }, owner);
+  delete process.env.ENABLE_RESYNC;
+});
+
+describe('source-docs routes', () => {
+  it('POST scoped to resource creates row', async () => {
+    const res = await request(app)
+      .post(`/api/resources/${resource.id}/source-docs`).set(ownerHeaders)
+      .send({ name: 'README', upstream_url: 'https://docs.example/readme' });
+    expect(res.status).toBe(201);
+    expect(res.body.resource_id).toBe(resource.id);
+  });
+
+  it('GET /:id and PATCH update', async () => {
+    const c = await request(app)
+      .post(`/api/resources/${resource.id}/source-docs`).set(ownerHeaders)
+      .send({ name: 'CONFIG', upstream_url: 'https://docs.example/c' });
+    const get = await request(app).get(`/api/source-docs/${c.body.id}`).set(ownerHeaders);
+    expect(get.body.name).toBe('CONFIG');
+    const patched = await request(app).patch(`/api/source-docs/${c.body.id}`).set(ownerHeaders)
+      .send({ version: '1.2.3' });
+    expect(patched.body.version).toBe('1.2.3');
+  });
+
+  it('POST /:id/resync without env → 503', async () => {
+    const c = await request(app)
+      .post(`/api/resources/${resource.id}/source-docs`).set(ownerHeaders)
+      .send({ name: 'doc', upstream_url: 'https://docs.example/d' });
+    const res = await request(app)
+      .post(`/api/source-docs/${c.body.id}/resync`).set(ownerHeaders);
+    expect(res.status).toBe(503);
+    expect(res.body.error.code).toBe('feature_disabled');
+  });
+
+  it('POST /:id/resync with env=true → 202', async () => {
+    process.env.ENABLE_RESYNC = 'true';
+    const c = await request(app)
+      .post(`/api/resources/${resource.id}/source-docs`).set(ownerHeaders)
+      .send({ name: 'doc', upstream_url: 'https://docs.example/d' });
+    const res = await request(app)
+      .post(`/api/source-docs/${c.body.id}/resync`).set(ownerHeaders);
+    expect(res.status).toBe(202);
+    expect(res.body.queued).toBe(true);
+  });
+});