@dfsramos/foreman 0.0.0-stage → 0.2.0

package/dist/server/app.js

@@ -0,0 +1,344 @@
+import path from 'node:path';
+import fastifyStatic from '@fastify/static';
+import Fastify from 'fastify';
+import { loadAgentsConfig, saveAgentsConfig } from '../agent/config.js';
+import { ADAPTERS } from '../agent/registry.js';
+import { RUN_STATUSES } from '../db.js';
+import { DEFAULT_IGNORED_AUTHORS, DEFAULT_REVIEW_ROUNDS, maskProject, PRIORITIES, REVIEW_MODES, validateProject } from '../projects.js';
+import { SOURCE_TYPES } from '../sources/registry.js';
+import { registerImportRoutes } from './imports.js';
+import { registerTaskRoutes } from './tasks.js';
+const PUBLIC_DIR = path.join(import.meta.dirname, '../../public');
+const KEEP_ALIVE_MS = 25_000;
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 200;
+function parseInteger(value, fallback) {
+    if (value === undefined || value === '')
+        return fallback;
+    return /^\d+$/.test(value) ? Number(value) : null;
+}
+const idParam = (value) => (/^\d+$/.test(value) ? Number(value) : NaN);
+export function buildApp({ runner, db, env, availability, adapters = ADAPTERS, sourceTypes = SOURCE_TYPES, importTypes, projectTasks }) {
+    const app = Fastify({ logger: false });
+    const streams = new Set();
+    const statusView = () => {
+        const status = runner.getStatus();
+        const names = new Map(db.listProjects().map((project) => [project.id, project]));
+        return {
+            state: status.state,
+            projects: status.projects.map((project) => ({
+                ...project,
+                name: names.get(project.id)?.name ?? `Project ${project.id}`,
+                priority: names.get(project.id)?.priority ?? 'normal',
+            })),
+            activeRunIds: status.activeRunIds,
+            activeRuns: status.activeRunIds.flatMap((id) => db.getRun(id) ?? []),
+        };
+    };
+    const projectsView = () => ({
+        projects: db.listProjects().map((project) => ({ ...maskProject(project, sourceTypes), status: runner.projectStatus(project.id) })),
+        sources: sourceTypes.map((type) => ({ id: type.id, name: type.name, fields: type.fields })),
+        priorities: PRIORITIES,
+        reviewModes: REVIEW_MODES,
+        defaults: {
+            pollIntervalSeconds: 60,
+            agentTimeoutMinutes: 30,
+            worktreeRoot: path.join(env.dataDir, 'worktrees'),
+            reviewMaxRounds: DEFAULT_REVIEW_ROUNDS,
+            reviewIgnoreAuthors: DEFAULT_IGNORED_AUTHORS,
+            reviewMode: 'none',
+            waitForCi: true,
+        },
+    });
+    const agentsView = () => {
+        const config = loadAgentsConfig(db, env, adapters);
+        const usage = runner.getUsage();
+        const stats = db.agentStats();
+        const active = new Map();
+        for (const id of runner.getStatus().activeRunIds) {
+            const agent = db.getRun(id)?.agent;
+            if (agent)
+                active.set(agent, (active.get(agent) ?? 0) + 1);
+        }
+        return {
+            order: config.order,
+            agents: config.order.flatMap((id) => {
+                const adapter = adapters.find((candidate) => candidate.id === id);
+                const entry = config.agents[id];
+                if (!adapter || !entry)
+                    return [];
+                const probe = availability.get(id);
+                return [
+                    {
+                        id,
+                        name: adapter.name,
+                        verified: adapter.verified,
+                        notes: adapter.notes ?? [],
+                        defaultBin: adapter.defaultBin,
+                        fields: adapter.fields,
+                        available: probe?.available ?? false,
+                        version: probe?.version ?? null,
+                        error: probe?.error ?? null,
+                        enabled: entry.enabled,
+                        maxConcurrent: entry.maxConcurrent,
+                        maxUsagePercent: entry.maxUsagePercent ?? null,
+                        allowOverage: entry.allowOverage ?? false,
+                        reportsUsage: adapter.reportsUsage === true,
+                        usage: usage[id] ?? null,
+                        paused: runner.pauseReason({ id, maxUsagePercent: entry.maxUsagePercent ?? null, allowOverage: entry.allowOverage ?? false }),
+                        signedOut: runner.signedOut(id),
+                        stats: stats[id] ?? null,
+                        bin: entry.bin ?? '',
+                        settings: entry.settings,
+                        active: active.get(id) ?? 0,
+                    },
+                ];
+            }),
+        };
+    };
+    const validationOptions = (existing) => ({
+        existing,
+        others: db.listProjects().filter((project) => project.id !== existing?.id),
+        dataDir: env.dataDir,
+        agentIds: adapters.map((adapter) => adapter.id),
+        sourceTypes,
+    });
+    /** Tries a project's source settings against its tracker. A check that throws is a failed check, not a failed request. */
+    const checkSource = async (project) => {
+        const type = sourceTypes.find((candidate) => candidate.id === project.sourceType);
+        if (!type)
+            return { ok: false, message: `${project.sourceType} is not a known source` };
+        try {
+            return await type.check(project.sourceSettings, { repoPath: project.repoPath, dataDir: env.dataDir });
+        }
+        catch (error) {
+            return { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+    };
+    // There is no authentication, so the browser is the main threat: another site must not be able to
+    // reach this API through DNS rebinding (Host check) or cross-site requests (Origin check).
+    const exposed = !LOOPBACK_HOSTS.has(env.host);
+    app.addHook('onRequest', async (request, reply) => {
+        const host = request.headers.host ?? '';
+        const hostname = host.replace(/:\d+$/, '').toLowerCase();
+        if (!exposed && !LOOPBACK_HOSTS.has(hostname)) {
+            return reply.code(403).send({ error: 'Requests must be addressed to a loopback host' });
+        }
+        const origin = request.headers.origin;
+        if (origin !== undefined && request.method !== 'GET' && request.method !== 'HEAD') {
+            if (!URL.canParse(origin) || new URL(origin).host !== host) {
+                return reply.code(403).send({ error: 'Cross-origin requests are not allowed' });
+            }
+        }
+    });
+    /* ---------- runner ---------- */
+    app.get('/api/status', async () => statusView());
+    app.post('/api/runner/start', async (_request, reply) => {
+        if (db.listProjects().length === 0)
+            return reply.code(409).send({ error: 'There are no projects to start' });
+        if (runner.startAll() === 0)
+            return reply.code(409).send({ error: 'Every project is already started' });
+        return statusView();
+    });
+    app.post('/api/runner/stop', async (_request, reply) => {
+        if (runner.stopAll() === 0)
+            return reply.code(409).send({ error: 'No project is started' });
+        return statusView();
+    });
+    /* ---------- projects ---------- */
+    app.get('/api/projects', async () => projectsView());
+    app.post('/api/projects', async (request, reply) => {
+        const result = validateProject(request.body, validationOptions());
+        if ('errors' in result)
+            return reply.code(400).send({ errors: result.errors });
+        db.createProject(result.project);
+        // The project is stored whatever the check finds; the check's message says what to fix.
+        const check = await checkSource(result.project);
+        return reply.code(201).send({ ...projectsView(), check });
+    });
+    app.put('/api/projects/:id', async (request, reply) => {
+        const existing = db.getProject(idParam(request.params.id));
+        if (!existing)
+            return reply.code(404).send({ error: 'Project not found' });
+        const result = validateProject(request.body, validationOptions(existing));
+        if ('errors' in result)
+            return reply.code(400).send({ errors: result.errors });
+        // Moving a project to another repository under running agents would strand their worktrees.
+        if (result.project.repoPath !== existing.repoPath && runner.projectStatus(existing.id).activeRunIds.length > 0) {
+            return reply.code(409).send({ error: 'The repository cannot be changed while the project has runs in progress' });
+        }
+        db.updateProject(existing.id, result.project);
+        const check = await checkSource(result.project);
+        return { ...projectsView(), check };
+    });
+    app.delete('/api/projects/:id', async (request, reply) => {
+        const existing = db.getProject(idParam(request.params.id));
+        if (!existing)
+            return reply.code(404).send({ error: 'Project not found' });
+        if (!runner.forgetProject(existing.id)) {
+            return reply.code(409).send({ error: 'Stop the project and wait for its runs to finish before deleting it' });
+        }
+        db.deleteProject(existing.id);
+        return projectsView();
+    });
+    app.post('/api/projects/:id/start', async (request, reply) => {
+        const id = idParam(request.params.id);
+        if (!db.getProject(id))
+            return reply.code(404).send({ error: 'Project not found' });
+        if (!runner.startProject(id))
+            return reply.code(409).send({ error: 'The project is already started or still stopping' });
+        return statusView();
+    });
+    app.post('/api/projects/:id/stop', async (request, reply) => {
+        const id = idParam(request.params.id);
+        if (!db.getProject(id))
+            return reply.code(404).send({ error: 'Project not found' });
+        if (!runner.stopProject(id))
+            return reply.code(409).send({ error: 'The project is not started' });
+        return statusView();
+    });
+    /** Tries source settings against the tracker. For an existing project, secrets left empty use the stored ones. */
+    app.post('/api/projects/check', async (request, reply) => {
+        const existing = typeof request.body?.id === 'number' ? db.getProject(request.body.id) : undefined;
+        const result = validateProject(request.body, { ...validationOptions(existing), sourceOnly: true });
+        if ('errors' in result) {
+            const sourceErrors = Object.fromEntries(Object.entries(result.errors).filter(([key]) => key.startsWith('source') || key === '_'));
+            if (Object.keys(sourceErrors).length > 0)
+                return reply.code(400).send({ errors: sourceErrors });
+        }
+        if (!('project' in result))
+            return reply.code(400).send({ errors: { sourceType: 'is not a known source' } });
+        return checkSource(result.project);
+    });
+    /**
+     * Lists what a source's credentials can see, so the form can offer choices instead of asking for ids.
+     * Only the secrets need to be filled in; for an existing project, secrets left empty use the stored ones.
+     */
+    app.post('/api/projects/lookup', async (request, reply) => {
+        const type = sourceTypes.find((candidate) => candidate.id === request.body?.sourceType);
+        if (!type)
+            return reply.code(400).send({ errors: { sourceType: 'is not a known source' } });
+        if (!type.lookup)
+            return { ok: false, message: `${type.name} cannot list its options; enter the values by hand.` };
+        const existing = typeof request.body.id === 'number' ? db.getProject(request.body.id) : undefined;
+        const settings = {};
+        const errors = {};
+        for (const field of type.fields) {
+            const raw = request.body.sourceSettings?.[field.key];
+            let value = typeof raw === 'string' ? raw.trim() : '';
+            if (value === '' && field.type === 'secret' && existing?.sourceType === type.id)
+                value = existing.sourceSettings[field.key] ?? '';
+            if (value === '' && field.type === 'secret' && field.required)
+                errors[`sourceSettings.${field.key}`] = 'is required';
+            settings[field.key] = value;
+        }
+        if (Object.keys(errors).length > 0)
+            return reply.code(400).send({ errors });
+        try {
+            return { ok: true, options: await type.lookup(settings) };
+        }
+        catch (error) {
+            return { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+    });
+    /* ---------- imports ---------- */
+    registerImportRoutes(app, { db, dataDir: env.dataDir, importTypes });
+    /* ---------- tasks ---------- */
+    registerTaskRoutes(app, { db, dataDir: env.dataDir, projectTasks });
+    /* ---------- runs ---------- */
+    app.get('/api/runs', async (request, reply) => {
+        const { status } = request.query;
+        if (status !== undefined && status !== '' && !RUN_STATUSES.includes(status)) {
+            return reply.code(400).send({ error: `Unknown status "${status}"` });
+        }
+        const limit = parseInteger(request.query.limit, DEFAULT_PAGE_SIZE);
+        const offset = parseInteger(request.query.offset, 0);
+        const projectId = parseInteger(request.query.project, -1);
+        if (limit === null || offset === null || projectId === null || limit < 1) {
+            return reply.code(400).send({ error: 'limit, offset and project must be non-negative whole numbers' });
+        }
+        const page = db.listRuns({
+            status: status ? status : undefined,
+            projectId: projectId >= 0 ? projectId : undefined,
+            limit: Math.min(limit, MAX_PAGE_SIZE),
+            offset,
+        });
+        // counts always cover every run, whatever the filter, so the UI can label its filters.
+        return { ...page, counts: db.countRuns() };
+    });
+    app.get('/api/runs/:id', async (request, reply) => {
+        const run = db.getRun(idParam(request.params.id));
+        if (!run)
+            return reply.code(404).send({ error: 'Run not found' });
+        return run;
+    });
+    app.get('/api/runs/:id/events', async (request, reply) => {
+        const run = db.getRun(idParam(request.params.id));
+        if (!run)
+            return reply.code(404).send({ error: 'Run not found' });
+        const after = parseInteger(request.query.after, 0);
+        if (after === null)
+            return reply.code(400).send({ error: 'after must be a non-negative whole number' });
+        return { events: db.listEvents(run.id, after) };
+    });
+    app.post('/api/runs/:id/abort', async (request, reply) => {
+        if (!runner.abort(idParam(request.params.id)))
+            return reply.code(409).send({ error: 'That run is not in progress' });
+        return statusView();
+    });
+    /* ---------- agents ---------- */
+    app.get('/api/agents', async () => agentsView());
+    app.put('/api/agents', async (request, reply) => {
+        const result = saveAgentsConfig(db, request.body, adapters);
+        if ('errors' in result)
+            return reply.code(400).send({ errors: result.errors });
+        // A changed binary path changes what is installed.
+        await availability.refresh(result.config);
+        return agentsView();
+    });
+    app.post('/api/agents/refresh', async () => {
+        await availability.refresh(loadAgentsConfig(db, env, adapters));
+        return agentsView();
+    });
+    /* ---------- live updates ---------- */
+    app.get('/api/stream', (request, reply) => {
+        reply.hijack();
+        const response = reply.raw;
+        response.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+        });
+        const send = (event, data) => {
+            response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+        };
+        const onStatus = () => send('status', statusView());
+        const onRun = (run) => send('run', run);
+        const onLog = (event) => send('log', event);
+        // Usage changes what the agents view shows (percentages, pauses), so the whole view is resent.
+        const onUsage = () => send('agents', agentsView());
+        runner.on('status', onStatus);
+        runner.on('run', onRun);
+        runner.on('log', onLog);
+        runner.on('usage', onUsage);
+        const keepAlive = setInterval(() => response.write(': keep-alive\n\n'), KEEP_ALIVE_MS);
+        streams.add(response);
+        onStatus();
+        request.raw.on('close', () => {
+            clearInterval(keepAlive);
+            runner.off('status', onStatus);
+            runner.off('run', onRun);
+            runner.off('log', onLog);
+            runner.off('usage', onUsage);
+            streams.delete(response);
+        });
+    });
+    // Open event streams would otherwise keep the server from closing.
+    app.addHook('preClose', async () => {
+        for (const response of streams)
+            response.end();
+    });
+    app.register(fastifyStatic, { root: PUBLIC_DIR });
+    return app;
+}

package/dist/server/imports.js

@@ -0,0 +1,182 @@
+import { maskConnection, resolveSettings, validateConnection } from '../imports/connections.js';
+import { IMPORT_TYPES } from '../imports/registry.js';
+import { gitDestination as createGitDestination } from '../sources/git-import.js';
+import { createKaneoApi, kaneoDestination } from '../sources/kaneo.js';
+const idParam = (value) => (typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : NaN);
+/** A filter from the request body, or what is wrong with it. */
+function parseFilter(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return { error: 'filter is required' };
+    const body = raw;
+    if (typeof body.teamId !== 'string' || body.teamId === '')
+        return { error: 'filter.teamId is required' };
+    if (body.projectId !== undefined && body.projectId !== null && typeof body.projectId !== 'string')
+        return { error: 'filter.projectId must be text' };
+    if (body.states !== undefined && (!Array.isArray(body.states) || body.states.some((state) => typeof state !== 'string'))) {
+        return { error: 'filter.states must be a list of state names' };
+    }
+    return {
+        filter: {
+            teamId: body.teamId,
+            ...(typeof body.projectId === 'string' && body.projectId !== '' ? { projectId: body.projectId } : {}),
+            ...(Array.isArray(body.states) && body.states.length > 0 ? { states: body.states } : {}),
+        },
+    };
+}
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+/** Routes for saved import connections, listing what they can see, and copying tasks into the tracker a project takes its work from. */
+export function registerImportRoutes(app, { db, dataDir, importTypes = IMPORT_TYPES, kaneoApi = createKaneoApi, gitDestination = createGitDestination }) {
+    /** What a project takes imports through, by the tracker it takes its work from. */
+    const destinations = {
+        kaneo: (project) => kaneoDestination(kaneoApi(project.sourceSettings), project.sourceSettings),
+        git: (project) => gitDestination(project.sourceSettings, { repoPath: project.repoPath, dataDir }),
+    };
+    const view = () => ({
+        connections: db.listImportConnections().map((connection) => maskConnection(connection, importTypes)),
+        types: importTypes.map((type) => ({ id: type.id, name: type.name, fields: type.fields })),
+    });
+    const typeOf = (id) => importTypes.find((candidate) => candidate.id === id);
+    app.get('/api/imports', async () => view());
+    app.post('/api/imports', async (request, reply) => {
+        const result = validateConnection(request.body, { others: db.listImportConnections(), types: importTypes });
+        if ('errors' in result)
+            return reply.code(400).send({ errors: result.errors });
+        db.createImportConnection(result.connection);
+        return reply.code(201).send(view());
+    });
+    app.put('/api/imports/:id', async (request, reply) => {
+        const existing = db.getImportConnection(idParam(request.params.id));
+        if (!existing)
+            return reply.code(404).send({ error: 'Import connection not found' });
+        const result = validateConnection(request.body, {
+            existing,
+            others: db.listImportConnections().filter((connection) => connection.id !== existing.id),
+            types: importTypes,
+        });
+        if ('errors' in result)
+            return reply.code(400).send({ errors: result.errors });
+        db.updateImportConnection(existing.id, result.connection);
+        return view();
+    });
+    app.delete('/api/imports/:id', async (request, reply) => {
+        const existing = db.getImportConnection(idParam(request.params.id));
+        if (!existing)
+            return reply.code(404).send({ error: 'Import connection not found' });
+        db.deleteImportConnection(existing.id);
+        return view();
+    });
+    /** Settings typed into the form, with an existing connection's stored secrets filled in. */
+    const formSettings = (body) => {
+        const type = typeOf(body?.type ?? '');
+        if (!type)
+            return null;
+        const existing = typeof body?.id === 'number' ? db.getImportConnection(body.id) : undefined;
+        return { type, settings: resolveSettings(type, body?.settings, existing) };
+    };
+    app.post('/api/imports/check', async (request, reply) => {
+        const form = formSettings(request.body);
+        if (!form)
+            return reply.code(400).send({ errors: { type: 'is not a known import source' } });
+        return form.type.check(form.settings);
+    });
+    app.post('/api/imports/lookup', async (request, reply) => {
+        const form = formSettings(request.body);
+        if (!form)
+            return reply.code(400).send({ errors: { type: 'is not a known import source' } });
+        try {
+            return { ok: true, options: await form.type.lookup(form.settings) };
+        }
+        catch (error) {
+            return { ok: false, message: messageOf(error) };
+        }
+    });
+    const importTarget = (raw) => {
+        if (raw === undefined || raw === null)
+            return { project: undefined };
+        const project = typeof raw === 'number' ? db.getProject(raw) : undefined;
+        if (!project)
+            return { status: 404, error: 'Target project not found' };
+        const destination = destinations[project.sourceType]?.(project);
+        if (!destination)
+            return { status: 400, error: 'The target project does not take its work from a tracker that takes imports' };
+        return { project, destination };
+    };
+    app.post('/api/imports/:id/tasks', async (request, reply) => {
+        const connection = db.getImportConnection(idParam(request.params.id));
+        const type = connection && typeOf(connection.type);
+        if (!connection || !type)
+            return reply.code(404).send({ error: 'Import connection not found' });
+        const parsed = parseFilter(request.body?.filter);
+        if ('error' in parsed)
+            return reply.code(400).send({ error: parsed.error });
+        const target = importTarget(request.body?.targetProjectId);
+        if ('error' in target)
+            return reply.code(target.status).send({ error: target.error });
+        try {
+            const tasks = await type.list(connection.settings, parsed.filter);
+            const imported = target.destination ? await target.destination.alreadyImported(type.id, tasks) : new Map();
+            return { tasks: tasks.map((task) => ({ ...task, imported: imported.get(task.id) ?? null })) };
+        }
+        catch (error) {
+            return reply.code(502).send({ error: messageOf(error) });
+        }
+    });
+    app.post('/api/imports/:id/import', async (request, reply) => {
+        const connection = db.getImportConnection(idParam(request.params.id));
+        const type = connection && typeOf(connection.type);
+        if (!connection || !type)
+            return reply.code(404).send({ error: 'Import connection not found' });
+        const parsed = parseFilter(request.body?.filter);
+        if ('error' in parsed)
+            return reply.code(400).send({ error: parsed.error });
+        const { taskIds } = request.body ?? {};
+        if (!Array.isArray(taskIds) || taskIds.length === 0 || taskIds.some((id) => typeof id !== 'string')) {
+            return reply.code(400).send({ error: 'taskIds must be a non-empty list of task ids' });
+        }
+        const target = importTarget(request.body?.targetProjectId);
+        if ('error' in target)
+            return reply.code(target.status).send({ error: target.error });
+        if (!target.destination)
+            return reply.code(400).send({ error: 'A target project is required' });
+        // The tasks are read again from the origin: what gets copied is never taken from the browser.
+        let listed;
+        try {
+            listed = await type.list(connection.settings, parsed.filter);
+        }
+        catch (error) {
+            return reply.code(502).send({ error: messageOf(error) });
+        }
+        const { destination } = target;
+        const imported = [];
+        const skipped = [];
+        const failed = [];
+        let already;
+        try {
+            already = await destination.alreadyImported(type.id, listed);
+        }
+        catch (error) {
+            return reply.code(502).send({ error: messageOf(error) });
+        }
+        // One at a time: trackers rate-limit per key (Kaneo 100 a window), and a failure is reported for its task alone.
+        for (const id of [...new Set(taskIds)]) {
+            const task = listed.find((candidate) => candidate.id === id);
+            if (!task) {
+                failed.push({ id, error: 'is not in the list for this filter' });
+                continue;
+            }
+            const held = already.get(id);
+            if (held) {
+                skipped.push({ id, targetIdentifier: held });
+                continue;
+            }
+            try {
+                const created = await destination.create(type.id, task);
+                imported.push({ id, identifier: task.identifier, targetIdentifier: created.identifier });
+            }
+            catch (error) {
+                failed.push({ id, identifier: task.identifier, error: messageOf(error) });
+            }
+        }
+        return { imported, skipped, failed };
+    });
+}

package/dist/server/tasks.js

@@ -0,0 +1,77 @@
+import { createTask } from '../sources/git-import.js';
+import { createGitSource } from '../sources/git.js';
+const MAX_TITLE_LENGTH = 200;
+const PRIORITY_RANGE = { min: 0, max: 4 };
+const idParam = (value) => (typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : NaN);
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+/** A project's git source, opened for one request; the store behind it is one per repository and branch, shared with the runner's. */
+const gitProjectTasks = (dataDir) => (project) => {
+    const source = createGitSource(project.sourceSettings, { repoPath: project.repoPath, dataDir });
+    return { inspect: () => source.inspect(), create: (input) => createTask(source, input) };
+};
+/** A whole number in `range`, from a number or a string of digits as the console's select sends it; null otherwise. */
+const wholeNumber = (value, range) => {
+    const n = typeof value === 'string' && /^\d+$/.test(value.trim()) ? Number(value) : value;
+    return typeof n === 'number' && Number.isInteger(n) && n >= range.min && n <= range.max ? n : null;
+};
+/** A new task from the request body, or what is wrong with it field by field, in the shape `validateProject` uses. */
+function parseNewTask(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return { errors: { _: 'Request body must be a JSON object' } };
+    }
+    const body = input;
+    const errors = {};
+    const title = typeof body.title === 'string' ? body.title.trim() : '';
+    if (body.title !== undefined && typeof body.title !== 'string')
+        errors.title = 'must be text';
+    else if (title === '')
+        errors.title = 'is required';
+    else if (title.length > MAX_TITLE_LENGTH)
+        errors.title = `must be at most ${MAX_TITLE_LENGTH} characters`;
+    const description = typeof body.description === 'string' ? body.description.trim() : '';
+    if (body.description !== undefined && body.description !== null && typeof body.description !== 'string')
+        errors.description = 'must be text';
+    const priority = wholeNumber(body.priority ?? PRIORITY_RANGE.min, PRIORITY_RANGE);
+    if (priority === null)
+        errors.priority = `must be a whole number between ${PRIORITY_RANGE.min} and ${PRIORITY_RANGE.max}`;
+    if (Object.keys(errors).length > 0)
+        return { errors };
+    return { task: { title, description: description === '' ? null : description, priority: priority } };
+}
+/** Routes that list a git-source project's task files with its lease, and add a task file to its branch. */
+export function registerTaskRoutes(app, { db, dataDir, projectTasks = gitProjectTasks(dataDir) }) {
+    /** The project's tasks, or why the request cannot have them. */
+    const tasksOf = (id) => {
+        const project = db.getProject(idParam(id));
+        if (!project)
+            return { status: 404, error: 'Project not found' };
+        if (project.sourceType !== 'git')
+            return { status: 400, error: 'Not a git-source project' };
+        return { tasks: projectTasks(project) };
+    };
+    app.get('/api/projects/:id/tasks', async (request, reply) => {
+        const target = tasksOf(request.params.id);
+        if ('error' in target)
+            return reply.code(target.status).send({ error: target.error });
+        try {
+            return await target.tasks.inspect();
+        }
+        catch (error) {
+            return reply.code(502).send({ error: messageOf(error) });
+        }
+    });
+    app.post('/api/projects/:id/tasks', async (request, reply) => {
+        const target = tasksOf(request.params.id);
+        if ('error' in target)
+            return reply.code(target.status).send({ error: target.error });
+        const parsed = parseNewTask(request.body);
+        if ('errors' in parsed)
+            return reply.code(400).send({ errors: parsed.errors });
+        try {
+            return reply.code(201).send(await target.tasks.create(parsed.task));
+        }
+        catch (error) {
+            return reply.code(502).send({ error: messageOf(error) });
+        }
+    });
+}

package/dist/sources/branch.js

@@ -0,0 +1,17 @@
+/**
+ * Text as a file or branch name part: lowercase, runs of anything but letters and digits as one
+ * dash, no dash at either end, at most 50 characters. Empty when the text has nothing to keep.
+ */
+export function slug(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 50)
+        .replace(/-+$/, '');
+}
+/** For trackers with no branch name of their own: one made from the task's identifier and title. */
+export function branchNameOf(identifier, title) {
+    const part = slug(title);
+    return part ? `${identifier.toLowerCase()}-${part}` : identifier.toLowerCase();
+}