@dfsramos/foreman 0.0.0-stage → 0.3.0

package/dist/sources/lease.js

@@ -0,0 +1,38 @@
+/**
+ * The project lease (ADR 0001): one machine at a time polls a git-source project, dispatches its
+ * tasks and acts on its reviews. The lease is a small file on the task branch that names the
+ * holder and when the lease runs out; the holder renews it while it polls, and a machine that
+ * finds it lapsed takes it over. This module is the decision alone and touches no file; the git
+ * source reads and writes the lease and acts on what is decided here.
+ */
+/** How long a lease lasts from the moment it is taken or renewed. */
+export const LEASE_TTL_MS = 10 * 60_000;
+/** The holder renews once less than this remains, so a poll that runs late still finds the lease its own. */
+export const LEASE_RENEW_MS = LEASE_TTL_MS / 2;
+/** A time as the files on the branch carry it: ISO 8601 in UTC, to the second. */
+export const stamp = (date) => date.toISOString().replace(/\.\d{3}Z$/, 'Z');
+/** Milliseconds the lease has left at `now`; an `until` that does not read as a time counts as run out. */
+const remaining = (lease, now) => {
+    const until = Date.parse(lease.until);
+    return Number.isNaN(until) ? 0 : until - now.getTime();
+};
+/** What `host` should do about the lease as it stands at `now`. A lease is lapsed from the second it names. */
+export function decideLease(lease, host, now) {
+    if (lease === null)
+        return { kind: 'take', from: null };
+    const left = remaining(lease, now);
+    if (left <= 0)
+        return { kind: 'take', from: lease.holder };
+    if (lease.holder === host)
+        return { kind: 'hold', renew: left < LEASE_RENEW_MS };
+    return { kind: 'wait', holder: lease.holder, until: lease.until };
+}
+/**
+ * The lease to write for `host` at `now`: it runs `LEASE_TTL_MS` from now, and `since` is kept
+ * from our own unlapsed lease so that it says when this machine started polling, not when it
+ * last renewed.
+ */
+export function nextLease(lease, host, now) {
+    const since = lease !== null && decideLease(lease, host, now).kind === 'hold' ? lease.since : stamp(now);
+    return { holder: host, since, until: stamp(new Date(now.getTime() + LEASE_TTL_MS)) };
+}

package/dist/sources/linear.js

@@ -0,0 +1,186 @@
+import { createLinearClient } from '../linear/client.js';
+import { createIssueApi } from '../linear/issues.js';
+import { fetchWorkspace } from '../linear/workspace.js';
+/** Only issues carrying this label are picked up, unless the project's label setting says otherwise. */
+export const DEFAULT_LABEL = 'foreman';
+/** A project saved before the label setting existed gets the default; an explicitly empty one means "any issue". */
+const labelOf = (settings) => (settings.label ?? DEFAULT_LABEL).trim();
+const names = (settings) => ({
+    target: settings.targetState ?? 'Todo',
+    inProgress: settings.inProgressState ?? 'In Progress',
+    success: settings.successState ?? 'In Review',
+    approval: settings.approvalState ?? 'Pending approval',
+    done: settings.doneState ?? 'Done',
+});
+/**
+ * A Linear project as a task source. Workflow states are looked up by name on every fetch, so a
+ * renamed or missing state is reported at the next poll rather than at some later claim.
+ */
+export function createLinearSource(settings, api) {
+    const stateNames = names(settings);
+    let states = null;
+    const resolved = async () => {
+        states ??= await api.resolveStates(settings.teamId ?? '', stateNames);
+        return states;
+    };
+    const teamId = settings.teamId ?? '';
+    const projectId = settings.projectId ?? '';
+    // The review states are only looked up when the review loop needs them, so a team without
+    // them can still have new work picked up.
+    const stateId = async (name) => (await api.findStateIds(teamId, [name]))[name];
+    const inState = async (name) => api.fetchCandidates(teamId, projectId, await stateId(name), labelOf(settings) || undefined);
+    return {
+        async fetchCandidates() {
+            states = await api.resolveStates(settings.teamId ?? '', stateNames);
+            return api.fetchCandidates(settings.teamId ?? '', settings.projectId ?? '', states.targetId, labelOf(settings) || undefined);
+        },
+        async claim(task) {
+            await api.moveIssue(task.id, (await resolved()).inProgressId);
+        },
+        async complete(task) {
+            await api.moveIssue(task.id, (await resolved()).successId);
+        },
+        fetchInReview: () => inState(stateNames.success),
+        fetchAwaitingApproval: () => inState(stateNames.approval),
+        async approve(task) {
+            await api.moveIssue(task.id, await stateId(stateNames.approval));
+        },
+        async finish(task) {
+            await api.moveIssue(task.id, await stateId(stateNames.done));
+        },
+        async comment(task, body) {
+            await api.addComment(task.id, body);
+        },
+        describe: () => ({
+            waiting: stateNames.target,
+            claimed: stateNames.inProgress,
+            done: stateNames.success,
+            approval: stateNames.approval,
+            finished: stateNames.done,
+        }),
+    };
+}
+/** Turns a workspace listing into options for the team, project and state fields. */
+export function workspaceOptions(teams) {
+    const states = [];
+    for (const team of teams) {
+        for (const name of team.states) {
+            const existing = states.find((option) => option.value === name);
+            if (existing)
+                existing.for.push(team.id);
+            else
+                states.push({ value: name, label: name, for: [team.id] });
+        }
+    }
+    const labels = [];
+    for (const team of teams) {
+        for (const name of team.labels) {
+            const existing = labels.find((option) => option.value.toLowerCase() === name.toLowerCase());
+            if (existing)
+                existing.for.push(team.id);
+            else
+                labels.push({ value: name, label: name, for: [team.id] });
+        }
+    }
+    return {
+        teamId: teams.map((team) => ({ value: team.id, label: `${team.name} (${team.key})` })),
+        projectId: teams.flatMap((team) => team.projects.map((project) => ({ value: project.id, label: project.name, for: [team.id] }))),
+        targetState: states,
+        inProgressState: states,
+        successState: states,
+        approvalState: states,
+        doneState: states,
+        label: labels,
+    };
+}
+export const linearSourceType = {
+    id: 'linear',
+    name: 'Linear',
+    fields: [
+        { key: 'apiKey', label: 'API key', type: 'secret', required: true, help: 'A Linear personal API key.' },
+        { key: 'teamId', label: 'Team', type: 'text', required: true, help: 'The team whose workflow states are used.', lookup: {} },
+        {
+            key: 'projectId',
+            label: 'Project',
+            type: 'text',
+            required: true,
+            help: 'The project issues are taken from.',
+            lookup: { dependsOn: 'teamId' },
+        },
+        {
+            key: 'targetState',
+            label: 'Target state',
+            type: 'text',
+            required: true,
+            default: 'Todo',
+            help: 'Issues are picked up from here.',
+            lookup: { dependsOn: 'teamId' },
+        },
+        {
+            key: 'inProgressState',
+            label: 'In-progress state',
+            type: 'text',
+            required: true,
+            default: 'In Progress',
+            help: 'Set on claim; kept on failure.',
+            lookup: { dependsOn: 'teamId' },
+        },
+        {
+            key: 'successState',
+            label: 'Review state',
+            type: 'text',
+            required: true,
+            default: 'In Review',
+            help: 'Set once the pull request is open. Foreman watches these for review feedback.',
+            lookup: { dependsOn: 'teamId' },
+        },
+        {
+            key: 'approvalState',
+            label: 'Approval state',
+            type: 'text',
+            required: true,
+            default: 'Pending approval',
+            help: 'Set once the review is positive: a person now approves and merges.',
+            lookup: { dependsOn: 'teamId' },
+        },
+        {
+            key: 'doneState',
+            label: 'Done state',
+            type: 'text',
+            required: true,
+            default: 'Done',
+            help: 'Set once the pull request is merged.',
+            lookup: { dependsOn: 'teamId' },
+        },
+        {
+            key: 'label',
+            label: 'Label',
+            type: 'text',
+            required: false,
+            default: DEFAULT_LABEL,
+            help: 'Only issues with this label are picked up. Empty picks up every issue in the target state.',
+            lookup: { dependsOn: 'teamId' },
+        },
+    ],
+    create(settings) {
+        return createLinearSource(settings, createIssueApi(createLinearClient(settings.apiKey ?? '')));
+    },
+    async check(settings) {
+        try {
+            const api = createIssueApi(createLinearClient(settings.apiKey ?? ''));
+            const states = await api.resolveStates(settings.teamId ?? '', names(settings));
+            const label = labelOf(settings);
+            const waiting = await api.fetchCandidates(settings.teamId ?? '', settings.projectId ?? '', states.targetId, label || undefined);
+            const count = waiting.length === 1 ? '1 issue is' : `${waiting.length} issues are`;
+            const labelled = label ? ` with the label "${label}"` : '';
+            return { ok: true, message: `Connected. All three states exist, and ${count} waiting in "${names(settings).target}"${labelled}.` };
+        }
+        catch (error) {
+            return { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+    },
+    async lookup(settings) {
+        return workspaceOptions(await fetchWorkspace(createLinearClient(settings.apiKey ?? '')));
+    },
+    summarise: (settings) => `Linear · ${names(settings).target} → ${names(settings).inProgress} → ${names(settings).success}${labelOf(settings) ? ` · label "${labelOf(settings)}"` : ' · any label'}`,
+};

package/dist/sources/options.js

@@ -0,0 +1,26 @@
+/** Turns a listing of projects into options for the project, state and label fields. */
+export function workspaceOptions(projects) {
+    const collect = (valuesOf) => {
+        const options = [];
+        for (const project of projects) {
+            for (const name of valuesOf(project)) {
+                const existing = options.find((option) => option.value.toLowerCase() === name.toLowerCase());
+                if (existing)
+                    existing.for.push(project.id);
+                else
+                    options.push({ value: name, label: name, for: [project.id] });
+            }
+        }
+        return options;
+    };
+    const states = collect((project) => project.states);
+    return {
+        projectId: projects.map((project) => ({ value: project.id, label: `${project.name} (${project.identifier})` })),
+        targetState: states,
+        inProgressState: states,
+        successState: states,
+        approvalState: states,
+        doneState: states,
+        label: collect((project) => project.labels),
+    };
+}

package/dist/sources/registry.js

@@ -0,0 +1,6 @@
+import { gitSourceType } from './git.js';
+import { kaneoSourceType } from './kaneo.js';
+import { linearSourceType } from './linear.js';
+/** Every kind of tracker foreman can take work from. */
+export const SOURCE_TYPES = [gitSourceType, linearSourceType, kaneoSourceType];
+export const getSourceType = (id, types = SOURCE_TYPES) => types.find((type) => type.id === id);

package/dist/sources/taskfile.js

@@ -0,0 +1,210 @@
+import { slug } from './branch.js';
+export const TASK_STATES = ['todo', 'in_progress', 'in_review', 'pending_approval', 'done'];
+/** A task file that does not follow the format; the message names the file. */
+export class TaskFileError extends Error {
+    constructor(name, reason) {
+        super(`${name}: ${reason}`);
+        this.name = 'TaskFileError';
+    }
+}
+const TASK_NAME = /^(\d+)-([a-z0-9-]+)\.md$/;
+const FRONTMATTER_KEY = /^[A-Za-z0-9_-]+$/;
+const TITLE_LINE = /^# (.+)$/;
+const LOG_HEADING = '## Log';
+const LOG_ENTRY = /^### (\d{4}-\d{2}-\d{2}T\S+)$/;
+/** The number and slug of a task file name, or null for any other name (other notes, dotfiles). */
+export function parseTaskName(name) {
+    const match = TASK_NAME.exec(name);
+    if (!match)
+        return null;
+    return { number: Number(match[1]), slug: match[2] };
+}
+const stateOf = (name, value) => {
+    if (value === undefined || value === '')
+        return 'todo';
+    if (TASK_STATES.includes(value))
+        return value;
+    throw new TaskFileError(name, `unknown state "${value}"`);
+};
+const priorityOf = (name, value) => {
+    if (value === undefined || value === '')
+        return 0;
+    if (!/^[0-4]$/.test(value))
+        throw new TaskFileError(name, `priority "${value}" is not a whole number from 0 to 4`);
+    return Number(value);
+};
+/** Lines of a body without their carriage returns, so a file edited on Windows reads the same. */
+const linesOf = (text) => text.split('\n').map((line) => line.replace(/\r$/, ''));
+/**
+ * Splits the frontmatter from the body. There is frontmatter only when line 1 is `---`; it runs
+ * to the next `---` line, and every non-blank line in between is `key: value` with the value
+ * being plain text to the end of the line.
+ */
+function splitFrontmatter(name, text) {
+    const lines = text.split('\n');
+    if (lines[0]?.replace(/\r$/, '') !== '---')
+        return { meta: {}, body: text };
+    const meta = {};
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i].replace(/\r$/, '');
+        if (line === '---')
+            return { meta, body: lines.slice(i + 1).join('\n') };
+        if (line.trim() === '')
+            continue;
+        const colon = line.indexOf(':');
+        if (colon <= 0)
+            throw new TaskFileError(name, `frontmatter line ${i + 1} is not "key: value"`);
+        meta[line.slice(0, colon).trim()] = line.slice(colon + 1).trim();
+    }
+    throw new TaskFileError(name, 'frontmatter is not closed');
+}
+/** Where the body's title line and log heading are, as line indexes; the log index is the line count when there is none. */
+function layoutOf(lines) {
+    const titleAt = lines.findIndex((line) => TITLE_LINE.test(line));
+    const logAt = lines.findIndex((line, index) => index > titleAt && line === LOG_HEADING);
+    return { titleAt, logAt: logAt === -1 ? lines.length : logAt };
+}
+/** The title and description a body gives, falling back to the file's slug for the title. */
+function derive(body, fileSlug) {
+    const lines = linesOf(body);
+    const { titleAt, logAt } = layoutOf(lines);
+    const title = titleAt === -1 ? fileSlug.replace(/-/g, ' ') : TITLE_LINE.exec(lines[titleAt])[1].trim();
+    const description = lines.slice(titleAt + 1, logAt).join('\n').trim();
+    return { title, description: description === '' ? null : description };
+}
+/** Parses one task file. Throws `TaskFileError` for a name that is not a task name or a file that breaks the format. */
+export function parseTaskFile(name, text) {
+    const parsed = parseTaskName(name);
+    if (!parsed)
+        throw new TaskFileError(name, 'file name is not <number>-<slug>.md');
+    const { meta, body } = splitFrontmatter(name, text);
+    return {
+        name,
+        number: parsed.number,
+        slug: parsed.slug,
+        state: stateOf(name, meta.state),
+        priority: priorityOf(name, meta.priority),
+        meta,
+        ...derive(body, parsed.slug),
+        body,
+    };
+}
+/** The frontmatter block (`state`, `priority`, then the other keys in `meta` order, empty values left out) followed by the body unchanged. */
+export function serialiseTaskFile(file) {
+    const lines = ['---', `state: ${file.state}`, `priority: ${file.priority}`];
+    for (const [key, value] of Object.entries(file.meta)) {
+        if (key === 'state' || key === 'priority' || value === '')
+            continue;
+        lines.push(`${key}: ${value}`);
+    }
+    lines.push('---');
+    return `${lines.join('\n')}\n${file.body}`;
+}
+/**
+ * The file with frontmatter keys set, or removed when the value is null. A change to `state` or
+ * `priority` is validated and updates the typed field too. The body is untouched.
+ */
+export function withMeta(file, changes) {
+    const meta = { ...file.meta };
+    for (const [key, value] of Object.entries(changes)) {
+        if (value === null) {
+            delete meta[key];
+            continue;
+        }
+        if (!FRONTMATTER_KEY.test(key))
+            throw new TaskFileError(file.name, `"${key}" is not a frontmatter key`);
+        if (/[\r\n]/.test(value))
+            throw new TaskFileError(file.name, `the value of "${key}" spans more than one line`);
+        meta[key] = value;
+    }
+    return { ...file, meta, state: stateOf(file.name, meta.state), priority: priorityOf(file.name, meta.priority) };
+}
+/** The entries under the `## Log` heading, in file order; empty when the body has no log. */
+export function logEntriesOf(file) {
+    const lines = linesOf(file.body);
+    const { logAt } = layoutOf(lines);
+    const entries = [];
+    let current = null;
+    const close = () => {
+        if (current)
+            entries.push({ at: current.at, text: current.lines.join('\n').trim() });
+    };
+    for (const line of lines.slice(logAt + 1)) {
+        const match = LOG_ENTRY.exec(line);
+        if (match) {
+            close();
+            current = { at: match[1], lines: [] };
+        }
+        else if (current) {
+            current.lines.push(line);
+        }
+    }
+    close();
+    return entries;
+}
+/** The file with a log entry added at the end of the body, under a `## Log` heading that is added when missing. */
+export function appendLog(file, at, text) {
+    const base = file.body.replace(/\s+$/, '');
+    const hasLog = linesOf(base).includes(LOG_HEADING);
+    const opened = hasLog ? base : base === '' ? LOG_HEADING : `${base}\n\n${LOG_HEADING}`;
+    const body = `${opened}\n\n### ${at}\n\n${text.trim()}\n`;
+    return { ...file, body, ...derive(body, file.slug) };
+}
+/**
+ * The file with a new title, description and priority. Only the title line and the description
+ * under it are rewritten: whatever precedes the title line, the `## Log` section and every other
+ * frontmatter key stay as they were. The file name is kept, so the identifier and the link to the
+ * file do not move when the title does.
+ */
+export function withContent(file, input) {
+    const title = input.title.replace(/\s+/g, ' ').trim();
+    if (title === '')
+        throw new TaskFileError(file.name, 'a task needs a title');
+    const description = input.description?.trim() ?? '';
+    const lines = linesOf(file.body);
+    const { titleAt, logAt } = layoutOf(lines);
+    const before = titleAt === -1 ? [] : lines.slice(0, titleAt);
+    const after = logAt === lines.length ? [] : ['', ...lines.slice(logAt)];
+    const written = description === '' ? [`# ${title}`] : [`# ${title}`, '', ...description.split(/\r?\n/)];
+    // A body that began with the frontmatter's closing line keeps its leading blank line.
+    const body = [...(titleAt === -1 ? [''] : []), ...before, ...written, ...after, ...(after.length === 0 ? [''] : [])].join('\n');
+    return { ...withMeta(file, { priority: String(input.priority) }), body, ...derive(body, file.slug) };
+}
+/** A fresh `todo` file for a task, as the import and the console create them. */
+export function newTaskFile(number, input) {
+    const title = input.title.replace(/\s+/g, ' ').trim();
+    const description = input.description?.trim() ?? '';
+    const body = description === '' ? `\n# ${title}\n` : `\n# ${title}\n\n${description}\n`;
+    const text = `---\nstate: todo\npriority: ${input.priority}\ncreated: ${input.created}\n---\n${body}`;
+    return parseTaskFile(taskFileName(number, title), text);
+}
+/** `<number>-<slug of the title>.md`; a title with nothing to slug gets `task` so the name still parses. */
+export function taskFileName(number, title) {
+    return `${number}-${slug(title) || 'task'}.md`;
+}
+/** The human-facing key of a task, e.g. `FM-12`. */
+export function identifierOf(prefix, number) {
+    return `${prefix}-${number}`;
+}
+/** The lease a file holds, or null when the file is missing or is not one JSON object with the three fields. */
+export function parseLease(text) {
+    if (text === null)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const { holder, since, until } = value;
+    if (typeof holder !== 'string' || typeof since !== 'string' || typeof until !== 'string')
+        return null;
+    return { holder, since, until };
+}
+/** One JSON object on one line with a trailing newline. */
+export function serialiseLease(lease) {
+    return `${JSON.stringify({ holder: lease.holder, since: lease.since, until: lease.until })}\n`;
+}

package/dist/sources/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@dfsramos/foreman",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Polling-and-dispatch daemon that hands tracker issues to coding-agent CLIs and follows their pull requests.",
+  "license": "MIT",
+  "author": "Daniel Ramos",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dfsramos/foreman.git"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "agents",
+    "linear",
+    "kaneo",
+    "git",
+    "automation"
+  ],
+  "type": "module",
+  "bin": {
+    "foreman": "dist/cli.js",
+    "fm": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "public",
+    "CHANGELOG.md"
+  ],
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "DATA_DIR=./data tsx watch --disable-warning=ExperimentalWarning src/cli.ts run",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "start": "DATA_DIR=./data node --disable-warning=ExperimentalWarning dist/cli.js run",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@fastify/static": "^10.1.5",
+    "dotenv": "^18.0.5",
+    "fastify": "^5.12.5",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.19.1",
+    "eslint": "^10.12.0",
+    "globals": "^17.13.0",
+    "tsx": "^4.23.15",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^5.0.3"
+  }
+}