@dfsramos/foreman 0.0.0-stage → 0.2.0

package/dist/sources/git-import.js

@@ -0,0 +1,60 @@
+import { importFooter } from '../imports/destination.js';
+import { createGitSource } from './git.js';
+import { identifierOf, newTaskFile, parseTaskName, serialiseTaskFile } from './taskfile.js';
+/** How often a create is retried when another machine takes the number it was about to use. */
+const MAX_ATTEMPTS = 5;
+/** A time as the files carry it: ISO 8601 in UTC, to the second. */
+const stamp = (date) => date.toISOString().replace(/\.\d{3}Z$/, 'Z');
+/** One more than the highest task number among `names`; 1 when none of them is a task file. */
+const nextNumber = (names) => Math.max(0, ...names.map((name) => parseTaskName(name)?.number ?? 0)) + 1;
+/**
+ * Writes a new task file with the next free number and pushes it under `Add <identifier>: <title>.`.
+ * The commit message has to name the number before the transaction runs, so the number is read
+ * first and checked again on the synced tree inside the transaction: when another machine took it
+ * in between, nothing is written and the next free number is tried, so two machines never end up
+ * with one number and every commit names the file it adds.
+ */
+export async function createTask(source, input, now = () => new Date()) {
+    if (input.title.trim() === '')
+        throw new Error('A task needs a title.');
+    const store = await source.store();
+    const created = stamp(now());
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+        const number = nextNumber((await source.readAll()).map((file) => file.name));
+        const file = newTaskFile(number, { ...input, created });
+        const identifier = identifierOf(source.prefix, number);
+        const pushed = await store.transact(`Add ${identifier}: ${file.title}.`, (tree) => nextNumber(tree.list(source.directory)) === number ? { [`${source.directory}/${file.name}`]: serialiseTaskFile(file) } : null);
+        if (pushed)
+            return { identifier, name: file.name };
+    }
+    throw new Error(`Gave up after ${MAX_ATTEMPTS} attempts: the next task number in ${source.directory} kept being taken.`);
+}
+/**
+ * A git source as the place imported tasks are copied into. A task file has no field for an
+ * external id, so the description ends with a line naming the origin, and that line is what later
+ * imports match. The source is opened here rather than passed in: the store behind it is one per
+ * repository and branch, so the destination shares the clone with the runner's source.
+ */
+export function gitDestination(settings, context, deps = {}) {
+    const source = createGitSource(settings, context, deps);
+    const now = deps.now ?? (() => new Date());
+    return {
+        trackerName: 'Git branch',
+        async alreadyImported(_source, tasks) {
+            const files = await source.readAll();
+            const found = new Map();
+            for (const task of tasks) {
+                const footer = importFooter(task);
+                const file = files.find((candidate) => candidate.description?.endsWith(footer));
+                if (file)
+                    found.set(task.id, identifierOf(source.prefix, file.number));
+            }
+            return found;
+        },
+        async create(_source, task) {
+            const text = task.description?.trim();
+            const created = await createTask(source, { title: task.title, description: text ? `${text}\n\n${importFooter(task)}` : importFooter(task), priority: task.priority }, now);
+            return { identifier: created.identifier };
+        },
+    };
+}

package/dist/sources/git.js

@@ -0,0 +1,430 @@
+import os from 'node:os';
+import path from 'node:path';
+import { openTaskStore } from '../git/taskstore.js';
+import { defaultExec } from '../git/worktree.js';
+import { branchNameOf } from './branch.js';
+import { decideLease, nextLease, stamp } from './lease.js';
+import { appendLog, identifierOf, parseLease, parseTaskFile, parseTaskName, serialiseLease, serialiseTaskFile, TASK_STATES, withMeta, } from './taskfile.js';
+export const DEFAULT_BRANCH = 'foreman';
+export const DEFAULT_DIRECTORY = '.foreman/tasks';
+export const DEFAULT_PREFIX = 'FM';
+/** How old the sync behind a read may be: the runner's three fetches of one poll share one sync. */
+const MAX_VIEW_AGE_MS = 5_000;
+/** The lease file, in the task directory; not a task name, so the task listing skips it. */
+const LEASE_FILE = '.lease';
+const NO_REPO_PATH = 'The Repository setting is needed until the project\'s repository path is set.';
+const NO_ORIGIN = 'This project has no "origin" remote; set Repository.';
+const GITHUB_REMOTE = /^(?:https:\/\/github\.com\/|git@github\.com:)([^/]+)\/([^/]+?)(?:\.git)?\/?$/;
+/** The tracker state names as people see them. */
+const STATE_NAMES = {
+    todo: 'todo',
+    in_progress: 'in progress',
+    in_review: 'in review',
+    pending_approval: 'pending approval',
+    done: 'done',
+};
+const settingsOf = (settings) => ({
+    repository: (settings.repository ?? '').trim(),
+    branch: (settings.branch ?? '').trim() || DEFAULT_BRANCH,
+    directory: (settings.directory ?? '').trim().replace(/^\.\/+|\/+$/g, '') || DEFAULT_DIRECTORY,
+    prefix: (settings.prefix ?? '').trim() || DEFAULT_PREFIX,
+});
+/** Where a person can read a task file: its page on GitHub for a GitHub remote, otherwise its path in the clone. */
+export function taskUrlOf(repository, branch, directory, name, cloneDir) {
+    const match = GITHUB_REMOTE.exec(repository);
+    return match ? `https://github.com/${match[1]}/${match[2]}/blob/${branch}/${directory}/${name}` : path.join(cloneDir, directory, name);
+}
+/** The clock and the name of this machine, as injected or from the system. */
+const clockOf = (deps) => ({
+    now: deps.now ?? (() => new Date()),
+    hostname: deps.hostname ?? (() => os.hostname()),
+});
+/** The lease as people see it: its holder and expiry while it stands, `mine` for this machine's own; null when missing or lapsed. */
+const standingLease = (lease, host, at) => {
+    const decision = decideLease(lease, host, at);
+    return lease !== null && decision.kind !== 'take' ? { holder: lease.holder, until: lease.until, mine: decision.kind === 'hold' } : null;
+};
+/** What the settings check says about the lease: who polls the project, or nobody when it is missing or lapsed. */
+const polledBy = (lease, host, at) => {
+    const standing = standingLease(lease, host, at);
+    return standing ? `Polled by ${standing.holder} until ${standing.until}.` : 'Not polled by any machine.';
+};
+const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
+/** What git says when a push had no usable credentials. */
+const AUTH_FAILURE = /could not read Username|Authentication failed|Permission denied|publickey|403|terminal prompts disabled/i;
+/** The fix for a push refused for want of credentials, by the kind of remote; nothing for a local path. */
+const pushHint = (repository) => /^https?:\/\//i.test(repository)
+    ? 'For an HTTPS remote, run `gh auth setup-git` or set up a credential helper for the account foreman runs under.'
+    : /^(ssh:\/\/|[^/:]+@)/.test(repository)
+        ? 'For an SSH remote, load the key into an agent foreman can reach, or use a key without a passphrase.'
+        : '';
+/** The message for a push to `repository` that was refused, with the fix when credentials are the cause. */
+export const describePushFailure = (repository, error) => {
+    const message = errorMessage(error);
+    const hint = AUTH_FAILURE.test(message) ? pushHint(repository) : '';
+    // Git's last line rarely ends in a full stop; the hint is a sentence of its own.
+    const joined = hint ? `${message}${/[.!?]$/.test(message) ? '' : '.'} ${hint}` : message;
+    return `Foreman cannot push to ${repository}: ${joined}`;
+};
+/** The `review` line of a file as progress, or null when it is not a JSON object with the two required fields. */
+function parseProgress(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const { handledUntil, rounds } = value;
+    if (typeof handledUntil !== 'string' || typeof rounds !== 'number')
+        return null;
+    return value;
+}
+export function createGitSource(settings, context, deps = {}) {
+    const { repository: configured, branch, directory, prefix } = settingsOf(settings);
+    const { now, hostname } = clockOf(deps);
+    const exec = deps.exec ?? defaultExec;
+    const pathOf = (name) => `${directory}/${name}`;
+    const identifier = (number) => identifierOf(prefix, number);
+    /** The project's `origin` remote, for a blank repository setting. */
+    const originOf = async () => {
+        if (context.repoPath === '')
+            throw new Error(NO_REPO_PATH);
+        let url;
+        try {
+            url = (await exec('git', ['-C', context.repoPath, 'remote', 'get-url', 'origin'])).stdout.trim();
+        }
+        catch {
+            throw new Error(NO_ORIGIN);
+        }
+        if (url === '')
+            throw new Error(NO_ORIGIN);
+        return url;
+    };
+    // Resolved once; a failure is not kept, so a remote added later is picked up by the next call.
+    let resolving = null;
+    const resolved = () => {
+        resolving ??= (async () => {
+            const repository = configured || (await originOf());
+            const store = openTaskStore({ repository, branch, dataDir: context.dataDir, ...(deps.exec ? { exec: deps.exec } : {}) });
+            return { repository, store };
+        })().catch((error) => {
+            resolving = null;
+            throw error;
+        });
+        return resolving;
+    };
+    /** The task files of a tree, by number. Two files with one number are an error, as is a file that does not parse. */
+    const filesIn = (tree) => {
+        const files = [];
+        const seen = new Map();
+        for (const name of tree.list(directory)) {
+            if (!parseTaskName(name))
+                continue;
+            const file = parseTaskFile(name, tree.read(pathOf(name)) ?? '');
+            const other = seen.get(file.number);
+            if (other !== undefined)
+                throw new Error(`Duplicate task number ${file.number} in ${directory}: ${other} and ${name}`);
+            seen.set(file.number, name);
+            files.push(file);
+        }
+        return files.sort((a, b) => a.number - b.number);
+    };
+    const fileOf = (files, id) => {
+        const file = files.find((candidate) => candidate.number === Number(id));
+        if (!file)
+            throw new Error(`Task ${id} was not found in ${directory}`);
+        return file;
+    };
+    const readAll = async (maxAgeMs = MAX_VIEW_AGE_MS) => {
+        const { store } = await resolved();
+        return filesIn(await store.view(maxAgeMs));
+    };
+    const toTask = ({ repository, store }, file) => {
+        const key = identifier(file.number);
+        return {
+            id: String(file.number),
+            identifier: key,
+            title: file.title,
+            description: file.description,
+            url: taskUrlOf(repository, branch, directory, file.name, store.dir),
+            priority: file.priority,
+            createdAt: file.meta.created ?? '',
+            branchName: file.meta.branch ?? branchNameOf(key, file.title),
+        };
+    };
+    const released = { claimed_by: null, claimed_at: null };
+    const leasePath = pathOf(LEASE_FILE);
+    const leaseIn = (tree) => parseLease(tree.read(leasePath));
+    /** Whether the decision has the lease file written: a take, or a hold that is due for renewal. */
+    const writesLease = (decision) => decision.kind === 'take' || (decision.kind === 'hold' && decision.renew);
+    /**
+     * Clears the claims `previous` left when it stopped renewing its lease, in one transaction: each
+     * of its tasks loses the claim and gets a log entry saying so, and keeps its state, which leaves
+     * the task where a locally failed run would (ADR 0001). Nothing is pushed when it left none.
+     */
+    const recoverClaims = async (previous) => {
+        const { store } = await resolved();
+        const note = `Foreman on ${previous} stopped renewing its lease while it held this task; ${hostname()} cleared the claim. The state was left as it was.`;
+        await store.transact(`Clear claims left by ${previous}.`, (tree) => {
+            const changes = {};
+            for (const file of filesIn(tree)) {
+                if (file.meta.claimed_by !== previous)
+                    continue;
+                changes[pathOf(file.name)] = serialiseTaskFile(appendLog(withMeta(file, released), stamp(now()), note));
+            }
+            return Object.keys(changes).length === 0 ? null : changes;
+        });
+    };
+    /**
+     * Decides on the lease as the synced view has it and, when it is to be taken or renewed, writes
+     * it in a transaction that decides again on the tree as it is on the remote, so that a lease
+     * another machine took in between is left to it. The fetches of one poll share the view's sync,
+     * so the first of them takes or renews and the rest find the lease as it left it. A take from
+     * another machine then clears that machine's claims. Returns what holds once that is done.
+     */
+    const ensureLease = async () => {
+        const host = hostname();
+        const { repository, store } = await resolved();
+        let decision = decideLease(leaseIn(await store.view(MAX_VIEW_AGE_MS)), host, now());
+        if (!writesLease(decision))
+            return decision;
+        try {
+            await store.transact(`Lease ${directory} to ${host}.`, (tree) => {
+                const at = now();
+                const current = leaseIn(tree);
+                decision = decideLease(current, host, at);
+                return writesLease(decision) ? { [leasePath]: serialiseLease(nextLease(current, host, at)) } : null;
+            });
+        }
+        catch (error) {
+            // The first push of a machine without credentials fails here, and the runner shows it as the project's error.
+            if (AUTH_FAILURE.test(errorMessage(error)))
+                throw new Error(describePushFailure(repository, error), { cause: error });
+            throw error;
+        }
+        if (decision.kind === 'take' && decision.from !== null && decision.from !== host)
+            await recoverClaims(decision.from);
+        return decision;
+    };
+    /** Whether this machine polls the project: it holds the lease, or has just taken it. */
+    const polling = async () => (await ensureLease()).kind !== 'wait';
+    const inState = async (state) => {
+        if (!(await polling()))
+            return [];
+        const current = await resolved();
+        return (await readAll()).filter((file) => file.state === state).map((file) => toTask(current, file));
+    };
+    /**
+     * Changes one task file in a transaction. `apply` runs on the file as it is on the remote after
+     * the sync, so its precondition holds when the push lands; it returns null for nothing to write.
+     */
+    const write = async (id, message, apply) => {
+        const { store } = await resolved();
+        await store.transact(message, (tree) => {
+            const next = apply(fileOf(filesIn(tree), id));
+            return next ? { [pathOf(next.name)]: serialiseTaskFile(next) } : null;
+        });
+    };
+    const lease = async () => {
+        const { store } = await resolved();
+        return leaseIn(await store.view(MAX_VIEW_AGE_MS));
+    };
+    const release = async () => {
+        // Nothing was taken through a store that was never opened, and a stop is no reason to clone one.
+        if (resolving === null)
+            return;
+        const host = hostname();
+        const { store } = await resolved();
+        await store.transact(`Release the lease on ${directory} from ${host}.`, (tree) => {
+            const current = leaseIn(tree);
+            // Only this machine's unlapsed lease is handed back: another machine's is left to it, and a lapsed one is free already.
+            return current !== null && decideLease(current, host, now()).kind === 'hold' ? { [leasePath]: serialiseLease({ ...current, until: stamp(now()) }) } : null;
+        });
+    };
+    /** A frontmatter value as the console shows it: a key that is missing or left blank is none. */
+    const metaOf = (file, key) => file.meta[key] || null;
+    const claimOf = (file) => `claimed by ${file.meta.claimed_by} since ${file.meta.claimed_at ?? 'an unknown time'}`;
+    /** Throws unless this machine holds the file's claim. */
+    const requireClaim = (file) => {
+        const holder = file.meta.claimed_by;
+        if (!holder)
+            throw new Error(`${identifier(file.number)} is not claimed`);
+        if (holder !== hostname())
+            throw new Error(`${identifier(file.number)} is ${claimOf(file)}, not by ${hostname()}`);
+    };
+    return {
+        directory,
+        prefix,
+        repository: async () => (await resolved()).repository,
+        store: async () => (await resolved()).store,
+        readAll,
+        lease,
+        release,
+        async inspect() {
+            // The files and the lease come from one sync: `readAll` syncs the view and `lease` reads it while it is fresh.
+            const { repository, store } = await resolved();
+            const files = await readAll();
+            return {
+                repository,
+                branch,
+                directory,
+                lease: standingLease(await lease(), hostname(), now()),
+                tasks: files.map((file) => ({
+                    id: String(file.number),
+                    identifier: identifier(file.number),
+                    title: file.title,
+                    state: file.state,
+                    priority: file.priority,
+                    claimedBy: metaOf(file, 'claimed_by'),
+                    claimedAt: metaOf(file, 'claimed_at'),
+                    pr: metaOf(file, 'pr'),
+                    branch: metaOf(file, 'branch'),
+                    url: taskUrlOf(repository, branch, directory, file.name, store.dir),
+                })),
+            };
+        },
+        async fetchCandidates() {
+            if (!(await polling()))
+                return [];
+            const current = await resolved();
+            return (await readAll())
+                .filter((file) => file.state === 'todo' && !file.meta.claimed_by)
+                .sort((a, b) => (a.priority || 5) - (b.priority || 5) || a.number - b.number)
+                .map((file) => toTask(current, file));
+        },
+        async claim(task) {
+            const host = hostname();
+            await write(task.id, `Claim ${identifier(Number(task.id))} on ${host}.`, (file) => {
+                const key = identifier(file.number);
+                const claim = { claimed_by: host, claimed_at: stamp(now()) };
+                if (file.meta.claimed_by)
+                    throw new Error(`${key} is ${file.state}, ${claimOf(file)}`);
+                if (file.state === 'todo') {
+                    // The branch is fixed at claim time so that a later change of the title does not move it.
+                    return withMeta(file, { state: 'in_progress', ...claim, branch: file.meta.branch ?? branchNameOf(key, file.title) });
+                }
+                // A review round: the task stays where it is while the agent works on the feedback.
+                if (file.state === 'in_review' || file.state === 'pending_approval')
+                    return withMeta(file, claim);
+                throw new Error(`${key} is ${file.state}`);
+            });
+        },
+        async complete(task) {
+            const key = identifier(Number(task.id));
+            // The commit message names the move; the move itself is decided on the synced file inside the transaction.
+            const moving = fileOf(await readAll(), task.id).state === 'in_progress';
+            await write(task.id, moving ? `Move ${key} to in review.` : `Release ${key}.`, (file) => {
+                requireClaim(file);
+                return withMeta(file, file.state === 'in_progress' ? { state: 'in_review', in_review_since: stamp(now()), ...released } : released);
+            });
+        },
+        fetchInReview: () => inState('in_review'),
+        fetchAwaitingApproval: () => inState('pending_approval'),
+        async approve(task) {
+            await write(task.id, `Move ${identifier(Number(task.id))} to pending approval.`, (file) => withMeta(file, { state: 'pending_approval', ...released }));
+        },
+        async finish(task) {
+            await write(task.id, `Move ${identifier(Number(task.id))} to done.`, (file) => withMeta(file, { state: 'done', ...released }));
+        },
+        async comment(task, body) {
+            await write(task.id, `Log on ${identifier(Number(task.id))}.`, (file) => appendLog(file, stamp(now()), body));
+        },
+        describe: () => ({
+            waiting: STATE_NAMES.todo,
+            claimed: STATE_NAMES.in_progress,
+            done: STATE_NAMES.in_review,
+            approval: STATE_NAMES.pending_approval,
+            finished: STATE_NAMES.done,
+        }),
+        async loadProgress(task) {
+            const file = fileOf(await readAll(), task.id);
+            const line = file.meta.review;
+            if (line !== undefined && line !== '') {
+                const progress = parseProgress(line);
+                return progress ? { ...progress, issueId: task.id } : null;
+            }
+            // Without a record, feedback older than the move to review was dealt with by whichever machine moved it.
+            const since = file.meta.in_review_since;
+            return since ? { issueId: task.id, handledUntil: since, rounds: 0 } : null;
+        },
+        async saveProgress(progress) {
+            const line = JSON.stringify(progress);
+            await write(progress.issueId, `Record review progress of ${identifier(Number(progress.issueId))}.`, (file) => file.meta.review === line ? null : withMeta(file, { review: line }));
+        },
+    };
+}
+/**
+ * Tries the settings: the repository resolves, the branch is on the remote or is created there as
+ * one empty commit, the clone syncs, a non-interactive push would be accepted, and every task file
+ * parses. Nothing but a missing branch is written, the lease included: the check reports who holds
+ * it without taking it.
+ */
+export async function checkGitSource(settings, context, deps = {}) {
+    const { branch, directory } = settingsOf(settings);
+    const { now, hostname } = clockOf(deps);
+    const source = createGitSource(settings, context, deps);
+    try {
+        const repository = await source.repository();
+        const store = await source.store();
+        const cannotPush = (error) => ({ ok: false, message: describePushFailure(repository, error) });
+        let created = false;
+        if ((await store.remoteBranch()) === null) {
+            try {
+                created = (await store.createBranch('Start the foreman task branch.')) === 'created';
+            }
+            catch (error) {
+                return cannotPush(error);
+            }
+        }
+        await store.sync();
+        try {
+            await store.canPush();
+        }
+        catch (error) {
+            return cannotPush(error);
+        }
+        const files = await source.readAll();
+        const counts = TASK_STATES.map((state) => `${files.filter((file) => file.state === state).length} ${STATE_NAMES[state]}`);
+        const total = files.length === 1 ? '1 task' : `${files.length} tasks`;
+        const polled = polledBy(await source.lease(), hostname(), now());
+        const made = created ? `Created branch "${branch}" in ${repository}. ` : '';
+        return { ok: true, message: `${made}Pushes work. ${total} in ${directory} on ${branch}: ${counts.join(', ')}. ${polled}` };
+    }
+    catch (error) {
+        return { ok: false, message: errorMessage(error) };
+    }
+}
+export const gitSourceType = {
+    id: 'git',
+    name: 'Git branch',
+    fields: [
+        {
+            key: 'repository',
+            label: 'Repository',
+            type: 'text',
+            required: false,
+            help: 'URL or path of the repository that holds the task files. Leave blank to use this project\'s own "origin" remote.',
+        },
+        {
+            key: 'branch',
+            label: 'Branch',
+            type: 'text',
+            required: true,
+            default: DEFAULT_BRANCH,
+            help: 'Created on the remote by Check source when it does not exist yet. Mind the spelling: a misspelt name becomes a new branch.',
+        },
+        { key: 'directory', label: 'Directory', type: 'text', required: true, default: DEFAULT_DIRECTORY },
+        { key: 'prefix', label: 'Identifier prefix', type: 'text', required: true, default: DEFAULT_PREFIX },
+    ],
+    create(settings, context) {
+        return createGitSource(settings, context);
+    },
+    check: (settings, context) => checkGitSource(settings, context),
+    summarise(settings) {
+        const { repository, branch, directory } = settingsOf(settings);
+        return `${repository || 'this repository'} · ${branch} · ${directory}`;
+    },
+};

package/dist/sources/kaneo.js

@@ -0,0 +1,156 @@
+import { importFooter } from '../imports/destination.js';
+import { createKaneoClient } from '../kaneo/client.js';
+import { createIssueApi } from '../kaneo/issues.js';
+import { fetchWorkspaces } from '../kaneo/workspace.js';
+import { workspaceOptions } from './options.js';
+/** Only tasks carrying this label are picked up, unless the project's label setting says otherwise. */
+export const DEFAULT_LABEL = 'foreman';
+/** An explicitly empty label means "any task". */
+const labelOf = (settings) => (settings.label ?? DEFAULT_LABEL).trim();
+const names = (settings) => ({
+    target: settings.targetState ?? 'To Do',
+    inProgress: settings.inProgressState ?? 'In Progress',
+    success: settings.successState ?? 'In Review',
+    approval: settings.approvalState ?? 'Pending approval',
+    done: settings.doneState ?? 'Done',
+});
+/** The Kaneo API for a project's settings. */
+export const createKaneoApi = (settings) => createIssueApi(createKaneoClient(settings.baseUrl ?? '', settings.apiKey ?? ''), {
+    baseUrl: settings.baseUrl ?? '',
+    projectId: settings.projectId ?? '',
+});
+/**
+ * A Kaneo project as a task source. Columns are looked up by name on every call, so a renamed or
+ * missing column is reported at the next poll rather than at some later claim. A task's status is the
+ * slug of its column, so each move resolves the name to a slug first.
+ */
+export function createKaneoSource(settings, api) {
+    const columnNames = names(settings);
+    const label = labelOf(settings) || undefined;
+    const slugOf = async (name) => (await api.findColumnSlugs([name]))[name];
+    return {
+        async fetchCandidates() {
+            await api.findColumnSlugs([columnNames.target, columnNames.inProgress, columnNames.success]);
+            return api.fetchInState(columnNames.target, label);
+        },
+        async claim(task) {
+            await api.moveTask(task.id, await slugOf(columnNames.inProgress));
+        },
+        async complete(task) {
+            await api.moveTask(task.id, await slugOf(columnNames.success));
+        },
+        fetchInReview: () => api.fetchInState(columnNames.success, label),
+        fetchAwaitingApproval: () => api.fetchInState(columnNames.approval, label),
+        async approve(task) {
+            await api.moveTask(task.id, await slugOf(columnNames.approval));
+        },
+        async finish(task) {
+            await api.moveTask(task.id, await slugOf(columnNames.done));
+        },
+        async comment(task, body) {
+            await api.addComment(task.id, body);
+        },
+        describe: () => ({
+            waiting: columnNames.target,
+            claimed: columnNames.inProgress,
+            done: columnNames.success,
+            approval: columnNames.approval,
+            finished: columnNames.done,
+        }),
+    };
+}
+const stateField = (key, label, def, help) => ({
+    key,
+    label,
+    type: 'text',
+    required: true,
+    default: def,
+    help,
+    lookup: { dependsOn: 'projectId' },
+});
+export const kaneoSourceType = {
+    id: 'kaneo',
+    name: 'Kaneo',
+    fields: [
+        {
+            key: 'baseUrl',
+            label: 'Kaneo address',
+            type: 'text',
+            required: true,
+            help: 'Where Kaneo is served, e.g. http://localhost:5173. The API is expected under /api.',
+        },
+        { key: 'apiKey', label: 'API key', type: 'secret', required: true, help: 'A Kaneo API key (Settings, API keys).' },
+        { key: 'projectId', label: 'Project', type: 'text', required: true, help: 'The project tasks are taken from.', lookup: {} },
+        stateField('targetState', 'Target column', 'To Do', 'Tasks are picked up from here.'),
+        stateField('inProgressState', 'In-progress column', 'In Progress', 'Set on claim; kept on failure.'),
+        stateField('successState', 'Review column', 'In Review', 'Set once the pull request is open. Foreman watches these for review feedback.'),
+        stateField('approvalState', 'Approval column', 'Pending approval', 'Set once the review is positive: a person now approves and merges. Kaneo does not have this column by default: create it in the project.'),
+        stateField('doneState', 'Done column', 'Done', 'Set once the pull request is merged.'),
+        {
+            key: 'label',
+            label: 'Label',
+            type: 'text',
+            required: false,
+            default: DEFAULT_LABEL,
+            help: 'Only tasks with this label are picked up. Empty picks up every task in the target column.',
+            lookup: { dependsOn: 'projectId' },
+        },
+    ],
+    create(settings) {
+        return createKaneoSource(settings, createKaneoApi(settings));
+    },
+    async check(settings) {
+        try {
+            if (!(settings.baseUrl ?? '').trim())
+                throw new Error('The Kaneo address is not set.');
+            const api = createKaneoApi(settings);
+            const n = names(settings);
+            await api.findColumnSlugs([n.target, n.inProgress, n.success, n.approval, n.done]);
+            const label = labelOf(settings);
+            const waiting = await api.fetchInState(n.target, label || undefined);
+            const count = waiting.length === 1 ? '1 task is' : `${waiting.length} tasks are`;
+            const labelled = label ? ` with the label "${label}"` : '';
+            return { ok: true, message: `Connected. All five columns exist, and ${count} waiting in "${n.target}"${labelled}.` };
+        }
+        catch (error) {
+            return { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+    },
+    async lookup(settings) {
+        return workspaceOptions(await fetchWorkspaces(createKaneoClient(settings.baseUrl ?? '', settings.apiKey ?? '')));
+    },
+    summarise: (settings) => `Kaneo · ${names(settings).target} → ${names(settings).inProgress} → ${names(settings).success}${labelOf(settings) ? ` · label "${labelOf(settings)}"` : ' · any label'}`,
+};
+/**
+ * A Kaneo project as the place imported tasks are copied into. Kaneo has no external id on a task, so
+ * the description ends with a line naming the origin URL, and that line is what later imports match.
+ */
+export function kaneoDestination(api, settings) {
+    const column = names(settings).target;
+    const label = labelOf(settings) || undefined;
+    return {
+        trackerName: 'Kaneo',
+        async alreadyImported(_source, tasks) {
+            const held = await api.importedFrom();
+            const found = new Map();
+            for (const task of tasks) {
+                const identifier = held.get(task.url);
+                if (identifier)
+                    found.set(task.id, identifier);
+            }
+            return found;
+        },
+        async create(_source, task) {
+            const text = task.description?.trim();
+            const created = await api.createTask({
+                title: task.title,
+                description: text ? `${text}\n\n${importFooter(task)}` : importFooter(task),
+                priority: task.priority,
+                columnName: column,
+                labelName: label,
+                link: { url: task.url, title: `Imported from ${task.identifier}` },
+            });
+            return { identifier: created.identifier };
+        },
+    };
+}