@dfsramos/foreman 0.0.0-stage → 0.3.0

package/dist/git/worktree.js

@@ -0,0 +1,248 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+export class GitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitError';
+    }
+}
+const COMMAND_TIMEOUT_MS = 120_000;
+const execFileAsync = promisify(execFile);
+/** Runs a command with git's prompts turned off and a timeout; the task store shares it. */
+export const defaultExec = (file, args, options) => execFileAsync(file, args, {
+    ...options,
+    maxBuffer: 16 * 1024 * 1024,
+    timeout: COMMAND_TIMEOUT_MS,
+    // Fail instead of waiting on a credential prompt nobody will answer.
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+});
+/** One state for a set of checks: any failure or cancellation fails it; else anything pending; else any pass; else none. */
+export function summariseChecks(checks) {
+    if (checks.some((check) => check.bucket === 'fail' || check.bucket === 'cancel'))
+        return 'failing';
+    if (checks.some((check) => check.bucket === 'pending'))
+        return 'pending';
+    return checks.some((check) => check.bucket === 'pass') ? 'passing' : 'none';
+}
+const CHECK_FIELDS = 'name,state,bucket,link,workflow';
+const LOG_EXCERPT_LIMIT = 4000;
+/** gh prefixes each line of a run's log with the job, the step and a timestamp. */
+const LOG_PREFIX = /^[^\t]*\t[^\t]*\t\S+Z ?/;
+/** The part of a failed run's log that shows why: the lines up to its last error, or its end when there is none. */
+function excerptLog(raw) {
+    const lines = raw.split('\n').map((line) => line.replace(LOG_PREFIX, ''));
+    const lastError = lines.findLastIndex((line) => line.includes('##[error]'));
+    const upTo = lastError >= 0 ? lines.slice(0, lastError + 1) : lines;
+    const kept = [];
+    let size = 0;
+    for (const line of upTo.reverse()) {
+        if (size + line.length + 1 > LOG_EXCERPT_LIMIT)
+            break;
+        kept.unshift(line);
+        size += line.length + 1;
+    }
+    return kept.join('\n').trim();
+}
+function describeFailure(file, args, error) {
+    const stderr = error.stderr?.trim();
+    const detail = stderr || (error instanceof Error ? error.message : String(error));
+    return `${file} ${args.join(' ')} failed: ${detail}`;
+}
+export function createGitApi(exec = defaultExec) {
+    const run = async (file, args, options) => {
+        try {
+            const { stdout } = await exec(file, args, options);
+            return stdout.trim();
+        }
+        catch (error) {
+            throw new GitError(describeFailure(file, args, error));
+        }
+    };
+    return {
+        async fetch(repoPath, signal) {
+            await run('git', ['-C', repoPath, 'fetch', 'origin', '--prune'], { signal });
+        },
+        async defaultBaseRef(repoPath, signal) {
+            try {
+                return await run('git', ['-C', repoPath, 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], { signal });
+            }
+            catch (error) {
+                throw new GitError(`Could not determine the default branch of ${repoPath}; run "git remote set-head origin --auto" there. ` +
+                    error.message);
+            }
+        },
+        async createWorktree({ repoPath, worktreeRoot, identifier, branch, baseRef, signal }) {
+            const worktreePath = path.join(worktreeRoot, identifier);
+            if (fs.existsSync(worktreePath)) {
+                throw new GitError(`worktree already exists at ${worktreePath}; remove it to retry`);
+            }
+            const branchExists = await exec('git', ['-C', repoPath, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], { signal }).then(() => true, () => false);
+            if (branchExists) {
+                throw new GitError(`branch ${branch} already exists; delete it to retry`);
+            }
+            fs.mkdirSync(worktreeRoot, { recursive: true });
+            // --no-track: otherwise the branch's upstream is the base branch and a bare "git push" targets it.
+            await run('git', ['-C', repoPath, 'worktree', 'add', '--no-track', '-b', branch, worktreePath, baseRef], { signal });
+            return worktreePath;
+        },
+        async removeWorktree(repoPath, worktreePath) {
+            // No --force: files the agent left uncommitted are kept rather than silently discarded.
+            await run('git', ['-C', repoPath, 'worktree', 'remove', worktreePath]);
+        },
+        async deleteBranchAt(repoPath, branch, ref) {
+            const commit = await run('git', ['-C', repoPath, 'rev-parse', '--verify', `${ref}^{commit}`]);
+            // update-ref with the old value deletes atomically, and refuses when the branch has moved on.
+            await run('git', ['-C', repoPath, 'update-ref', '-d', `refs/heads/${branch}`, commit]);
+        },
+        async checkoutWorktree({ repoPath, worktreeRoot, identifier, branch, signal }) {
+            const worktreePath = path.join(worktreeRoot, identifier);
+            if (fs.existsSync(worktreePath)) {
+                // A round that failed leaves its worktree behind. It is reused when that loses nothing: clean, on this
+                // branch, and not diverged from what was pushed (commits it has not pushed yet are kept). Otherwise it is left for a person to look at.
+                const refuse = (why) => new GitError(`worktree already exists at ${worktreePath} and ${why}; remove it to retry`);
+                const current = await run('git', ['-C', worktreePath, 'rev-parse', '--abbrev-ref', 'HEAD'], { signal }).catch(() => null);
+                if (current !== branch)
+                    throw refuse(current ? `is on ${current}` : 'is not a worktree');
+                if (await run('git', ['-C', worktreePath, 'status', '--porcelain'], { signal }))
+                    throw refuse('holds modified or untracked files');
+                await run('git', ['-C', worktreePath, 'merge', '--ff-only', `origin/${branch}`], { signal }).catch(() => {
+                    throw refuse('has diverged from what was pushed');
+                });
+                return worktreePath;
+            }
+            fs.mkdirSync(worktreeRoot, { recursive: true });
+            // -B: the local branch, if one is left from the first run, is reset to what was pushed.
+            await run('git', ['-C', repoPath, 'worktree', 'add', '-B', branch, worktreePath, `origin/${branch}`], { signal });
+            return worktreePath;
+        },
+        async pullRequest(repoPath, branch, signal) {
+            const json = async (args) => {
+                const stdout = await run('gh', args, { cwd: repoPath, signal });
+                try {
+                    return JSON.parse(stdout);
+                }
+                catch {
+                    throw new GitError(`gh ${args.slice(0, 2).join(' ')} returned unexpected output: ${stdout.slice(0, 200)}`);
+                }
+            };
+            const found = await json([
+                'pr', 'list', '--head', branch, '--state', 'all', '--json', 'number,url,state,createdAt,author', '--limit', '20',
+            ]);
+            const pr = found.find((candidate) => candidate.state === 'OPEN') ?? [...found].sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0];
+            if (!pr)
+                return null;
+            const view = await json(['pr', 'view', String(pr.number), '--json', 'reviews,comments,mergeable,baseRefName,headRefOid']);
+            // Comments on lines of the diff are not part of "pr view".
+            const inline = await json([
+                'api', `repos/{owner}/{repo}/pulls/${pr.number}/comments`, '--paginate',
+            ]);
+            const feedback = [
+                ...view.reviews.map((review) => ({
+                    id: review.id,
+                    kind: 'review',
+                    author: review.author?.login ?? 'unknown',
+                    body: review.body,
+                    state: review.state,
+                    createdAt: review.submittedAt,
+                })),
+                ...view.comments.map((comment) => ({
+                    id: comment.id,
+                    kind: 'comment',
+                    author: comment.author?.login ?? 'unknown',
+                    body: comment.body,
+                    createdAt: comment.createdAt,
+                })),
+                ...inline.map((comment) => ({
+                    id: String(comment.id),
+                    kind: 'inline',
+                    author: comment.user?.login ?? 'unknown',
+                    body: comment.body,
+                    path: comment.path,
+                    line: comment.line,
+                    createdAt: comment.created_at,
+                })),
+            ].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+            return {
+                number: pr.number,
+                url: pr.url,
+                state: pr.state,
+                author: pr.author?.login ?? 'unknown',
+                mergeable: view.mergeable === 'MERGEABLE' || view.mergeable === 'CONFLICTING' ? view.mergeable : 'UNKNOWN',
+                baseBranch: view.baseRefName ?? '',
+                headSha: view.headRefOid ?? '',
+                feedback,
+            };
+        },
+        async requestReview(repoPath, prNumber, logins, signal) {
+            const result = { requested: [], failed: [] };
+            for (const login of logins) {
+                // gh asks Copilot for a review through a special name, not its bot login.
+                const reviewer = /^copilot-pull-request-reviewer(\[bot\])?$/i.test(login) ? '@copilot' : login.replace(/\[bot\]$/, '');
+                try {
+                    await run('gh', ['pr', 'edit', String(prNumber), '--add-reviewer', reviewer], { cwd: repoPath, signal });
+                    result.requested.push(login);
+                }
+                catch (error) {
+                    result.failed.push({ login, reason: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            return result;
+        },
+        async findOpenPr(worktreePath, branch, signal) {
+            const stdout = await run('gh', ['pr', 'list', '--head', branch, '--state', 'open', '--json', 'url', '--limit', '1'], { cwd: worktreePath, signal });
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout);
+            }
+            catch {
+                throw new GitError(`gh pr list returned unexpected output: ${stdout.slice(0, 200)}`);
+            }
+            const first = Array.isArray(parsed) ? parsed[0] : undefined;
+            return typeof first?.url === 'string' ? first.url : null;
+        },
+        async ciStatus(repoPath, prNumber, signal) {
+            // gh exits 1 both when nothing is required and when there are no checks at all; neither is a failure here.
+            const checks = async (required) => {
+                const args = ['pr', 'checks', String(prNumber), ...(required ? ['--required'] : []), '--json', CHECK_FIELDS];
+                try {
+                    return await run('gh', args, { cwd: repoPath, signal });
+                }
+                catch (error) {
+                    if (error instanceof GitError && /no (required )?checks reported/.test(error.message))
+                        return null;
+                    throw error;
+                }
+            };
+            const stdout = (await checks(true)) ?? (await checks(false));
+            if (stdout === null)
+                return { state: 'none', checks: [] };
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout);
+            }
+            catch {
+                throw new GitError(`gh pr checks returned unexpected output: ${stdout.slice(0, 200)}`);
+            }
+            const list = parsed.map((check) => {
+                const run = /\/actions\/runs\/(\d+)/.exec(check.link);
+                return { name: check.name, bucket: check.bucket, state: check.state, link: check.link, runId: run ? Number(run[1]) : null };
+            });
+            return { state: summariseChecks(list), checks: list };
+        },
+        async failedLog(repoPath, runId, signal) {
+            try {
+                return excerptLog(await run('gh', ['run', 'view', String(runId), '--log-failed'], { cwd: repoPath, signal }));
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                return null;
+            }
+        },
+        async rerunFailed(repoPath, runId, signal) {
+            await run('gh', ['run', 'rerun', String(runId), '--failed'], { cwd: repoPath, signal });
+        },
+    };
+}

package/dist/imports/connections.js

@@ -0,0 +1,57 @@
+import { IMPORT_TYPES } from './registry.js';
+/**
+ * Settings from the console with the stored secrets filled in where the input left them empty.
+ * Unknown keys are dropped; use `validateConnection` to be told about them.
+ */
+export function resolveSettings(type, raw, existing) {
+    const given = typeof raw === 'object' && raw !== null ? raw : {};
+    const settings = {};
+    for (const field of type.fields) {
+        const value = typeof given[field.key] === 'string' ? given[field.key].trim() : '';
+        settings[field.key] = value === '' && field.type === 'secret' && existing?.type === type.id ? (existing.settings[field.key] ?? '') : value;
+    }
+    return settings;
+}
+/** Turns console input into a storable connection, or says what is wrong with it field by field. */
+export function validateConnection(input, { existing, others, types = IMPORT_TYPES }) {
+    const errors = {};
+    if (typeof input !== 'object' || input === null || Array.isArray(input))
+        return { errors: { _: 'Request body must be a JSON object' } };
+    const body = input;
+    const type = types.find((candidate) => candidate.id === body.type);
+    if (!type)
+        errors.type = 'is not a known import source';
+    const rawSettings = typeof body.settings === 'object' && body.settings !== null ? body.settings : {};
+    const settings = type ? resolveSettings(type, rawSettings, existing) : {};
+    for (const field of type?.fields ?? []) {
+        if (rawSettings[field.key] !== undefined && typeof rawSettings[field.key] !== 'string')
+            errors[`settings.${field.key}`] = 'must be text';
+        else if (settings[field.key] === '' && field.required)
+            errors[`settings.${field.key}`] = 'is required';
+    }
+    for (const key of Object.keys(rawSettings)) {
+        if (type && !type.fields.some((field) => field.key === key))
+            errors[`settings.${key}`] = 'is not a setting of this source';
+    }
+    const name = typeof body.name === 'string' ? body.name.trim() : '';
+    if (name === '')
+        errors.name = 'is required';
+    else if (name.length > 80)
+        errors.name = 'must be at most 80 characters';
+    else if (others.some((other) => other.name.toLowerCase() === name.toLowerCase()))
+        errors.name = 'is already used by another connection';
+    if (Object.keys(errors).length > 0)
+        return { errors };
+    return { connection: { name, type: type.id, settings } };
+}
+/** A connection as the console may see it: every secret replaced by whether it is set. */
+export function maskConnection(connection, types = IMPORT_TYPES) {
+    const type = types.find((candidate) => candidate.id === connection.type);
+    const settings = {};
+    // Settings without a known field are dropped rather than risk exposing a secret of a removed type.
+    for (const field of type?.fields ?? []) {
+        const value = connection.settings[field.key] ?? '';
+        settings[field.key] = field.type === 'secret' ? { set: value !== '' } : value;
+    }
+    return { ...connection, settings, summary: type?.summarise(connection.settings) ?? connection.type };
+}

package/dist/imports/destination.js

@@ -0,0 +1,2 @@
+/** The line that ends an imported task's description, naming where it came from. */
+export const importFooter = (task) => `Imported from ${task.identifier} · ${task.url}`;

package/dist/imports/linear.js

@@ -0,0 +1,40 @@
+import { listIssues } from '../linear/browse.js';
+import { createLinearClient } from '../linear/client.js';
+import { fetchWorkspace } from '../linear/workspace.js';
+/** Turns a workspace listing into options for the team, project and state filters. */
+export function importOptions(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] });
+        }
+    }
+    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] }))),
+        states,
+    };
+}
+export const linearImportType = {
+    id: 'linear',
+    name: 'Linear',
+    fields: [{ key: 'apiKey', label: 'API key', type: 'secret', required: true, help: 'A Linear personal API key. It is only used to read.' }],
+    list: (settings, filter) => listIssues(createLinearClient(settings.apiKey ?? ''), filter),
+    async lookup(settings) {
+        return importOptions(await fetchWorkspace(createLinearClient(settings.apiKey ?? '')));
+    },
+    async check(settings) {
+        try {
+            const teams = await fetchWorkspace(createLinearClient(settings.apiKey ?? ''));
+            return { ok: true, message: `Connected. ${teams.length === 1 ? '1 team is' : `${teams.length} teams are`} visible.` };
+        }
+        catch (error) {
+            return { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+    },
+    summarise: () => 'Linear · read-only',
+};

package/dist/imports/registry.js

@@ -0,0 +1,4 @@
+import { linearImportType } from './linear.js';
+/** Every kind of tracker foreman can read tasks from to import them. */
+export const IMPORT_TYPES = [linearImportType];
+export const getImportType = (id, types = IMPORT_TYPES) => types.find((type) => type.id === id);

package/dist/imports/types.js

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

package/dist/kaneo/client.js

@@ -0,0 +1,47 @@
+const REQUEST_TIMEOUT_MS = 30_000;
+export class KaneoError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'KaneoError';
+        this.status = status;
+    }
+}
+export function createKaneoClient(baseUrl, apiKey, fetchImpl = fetch) {
+    const root = `${baseUrl.trim().replace(/\/+$/, '')}/api`;
+    return {
+        async request(method, path, body) {
+            let response;
+            try {
+                response = await fetchImpl(`${root}${path}`, {
+                    method,
+                    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+                    body: body ? JSON.stringify(body) : undefined,
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                throw new KaneoError(`Kaneo API unreachable: ${reason}`);
+            }
+            if (response.status === 429) {
+                // X-RateLimit-Reset is a Unix time in seconds.
+                const reset = Number(response.headers.get('X-RateLimit-Reset'));
+                const when = Number.isFinite(reset) && reset > 0 ? `; the limit resets at ${new Date(reset * 1000).toISOString()}` : '';
+                throw new KaneoError(`Kaneo API rate limit reached${when}`, 429);
+            }
+            let parsed;
+            try {
+                parsed = await response.json();
+            }
+            catch {
+                parsed = undefined;
+            }
+            if (!response.ok) {
+                const message = parsed?.message;
+                throw new KaneoError(`Kaneo API returned HTTP ${response.status}${typeof message === 'string' ? `: ${message}` : ''}`, response.status);
+            }
+            return parsed;
+        },
+    };
+}

package/dist/kaneo/issues.js

@@ -0,0 +1,138 @@
+import { branchNameOf } from '../sources/branch.js';
+import { KaneoError } from './client.js';
+const PAGE_SIZE = 100;
+/** Bounds a listing against a page count that never ends; far outside normal use. */
+const MAX_PAGES = 100;
+const LABEL_COLOUR = '#6366f1';
+const PRIORITY = { urgent: 1, high: 2, medium: 3, low: 4 };
+const KANEO_PRIORITIES = ['no-priority', 'urgent', 'high', 'medium', 'low'];
+/** The line an imported task ends with; it is what lets a later import see that the task is already here. */
+const FOOTER = /^Imported from (\S+) · (\S+)\s*$/m;
+// "No priority" (0) sorts after "low" (4).
+const priorityRank = (priority) => (priority === 0 ? 5 : priority);
+const same = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
+export function createIssueApi(client, where) {
+    const projectId = encodeURIComponent(where.projectId);
+    const baseUrl = where.baseUrl.trim().replace(/\/+$/, '');
+    let identity;
+    const columns = () => client.request('GET', `/column/${projectId}`);
+    /** The project's key (`FS`) and its workspace's slug, which make up a task's identifier and address. */
+    const projectIdentity = () => {
+        identity ??= (async () => {
+            const project = await client.request('GET', `/project/${projectId}`);
+            const workspace = await client.request('GET', `/workspace/${encodeURIComponent(project.workspaceId)}`);
+            return { key: project.slug, workspaceSlug: workspace.slug, workspaceId: project.workspaceId };
+        })();
+        // A failed lookup must not stay cached.
+        identity.catch(() => {
+            identity = undefined;
+        });
+        return identity;
+    };
+    /** Every task a listing returns, across pages. */
+    const listBoard = async (filter) => {
+        const found = [];
+        for (let page = 1; page <= MAX_PAGES; page += 1) {
+            const query = new URLSearchParams({ ...filter, limit: String(PAGE_SIZE), page: String(page) });
+            const board = await client.request('GET', `/task/tasks/${projectId}?${query.toString()}`);
+            for (const column of board.data.columns)
+                found.push(...column.tasks);
+            if (page >= board.pagination.totalPages)
+                break;
+        }
+        return found;
+    };
+    /** The id of the workspace label with this name, creating it when only per-task copies exist. */
+    const labelId = async (workspaceId, name) => {
+        const all = await client.request('GET', `/label/workspace/${encodeURIComponent(workspaceId)}`);
+        // Attaching a label copies it to the task, so the copies carry a task id and are not the label.
+        const existing = all.find((label) => !label.taskId && same(label.name, name));
+        if (existing)
+            return existing.id;
+        return (await client.request('POST', '/label', { name, color: LABEL_COLOUR, workspaceId })).id;
+    };
+    const findColumnSlugs = async (names) => {
+        const all = await columns();
+        const slugs = {};
+        const missing = [];
+        for (const name of names) {
+            const slug = all.find((column) => same(column.name, name))?.slug;
+            if (slug)
+                slugs[name] = slug;
+            else
+                missing.push(name);
+        }
+        if (missing.length > 0) {
+            const quoted = [...new Set(missing)].map((name) => `"${name}"`).join(', ');
+            throw new KaneoError(`Column not found: ${quoted}. Available columns: ${all.map((column) => column.name).join(', ')}`);
+        }
+        return slugs;
+    };
+    return {
+        findColumnSlugs,
+        async fetchInState(columnName, label) {
+            const wanted = label?.trim() ?? '';
+            const slug = (await findColumnSlugs([columnName]))[columnName];
+            // Kaneo returns the whole board; with a status filter only the requested column holds tasks.
+            const found = await listBoard({ status: slug });
+            const matching = found.filter((item) => wanted === '' || item.labels.some((l) => same(l.name, wanted)));
+            if (matching.length === 0)
+                return [];
+            const { key, workspaceSlug } = await projectIdentity();
+            return matching
+                .map((item) => {
+                const identifier = `${key}-${item.number}`;
+                return {
+                    id: item.id,
+                    identifier,
+                    title: item.title,
+                    description: item.description?.trim() ? item.description : null,
+                    url: `${baseUrl}/${workspaceSlug}/task/${identifier}`,
+                    priority: PRIORITY[item.priority] ?? 0,
+                    createdAt: item.createdAt,
+                    branchName: branchNameOf(identifier, item.title),
+                };
+            })
+                .sort((a, b) => priorityRank(a.priority) - priorityRank(b.priority) || a.createdAt.localeCompare(b.createdAt));
+        },
+        async moveTask(taskId, statusSlug) {
+            await client.request('PUT', `/task/status/${encodeURIComponent(taskId)}`, { status: statusSlug });
+        },
+        async addComment(taskId, body) {
+            await client.request('POST', `/comment/${encodeURIComponent(taskId)}`, { content: body });
+        },
+        async createTask(input) {
+            // Resolved first so that a missing column is reported before anything is created.
+            const status = (await findColumnSlugs([input.columnName]))[input.columnName];
+            const { key, workspaceId } = await projectIdentity();
+            const created = await client.request('POST', `/task/${projectId}`, {
+                title: input.title,
+                description: input.description,
+                priority: KANEO_PRIORITIES[input.priority] ?? 'no-priority',
+                status,
+            });
+            const wanted = input.labelName?.trim();
+            if (wanted) {
+                await client.request('PUT', `/label/${encodeURIComponent(await labelId(workspaceId, wanted))}/task`, { taskId: created.id });
+            }
+            if (input.link) {
+                // The footer in the description is what de-duplication reads; the link is a convenience.
+                await client.request('POST', `/external-link/task/${encodeURIComponent(created.id)}`, input.link).catch(() => undefined);
+            }
+            return { id: created.id, identifier: `${key}-${created.number}` };
+        },
+        async importedFrom() {
+            const found = new Map();
+            const held = (await listBoard({})).flatMap((item) => {
+                const footer = item.description ? FOOTER.exec(item.description) : null;
+                return footer ? [{ item, url: footer[2] }] : [];
+            });
+            if (held.length === 0)
+                return found;
+            const { key } = await projectIdentity();
+            for (const { item, url } of held)
+                found.set(url, `${key}-${item.number}`);
+            return found;
+        },
+    };
+}

package/dist/kaneo/workspace.js

@@ -0,0 +1,24 @@
+/** The projects an API key can see, in every workspace it belongs to, each with its columns and labels. Read-only. */
+export async function fetchWorkspaces(client) {
+    const workspaces = await client.request('GET', '/workspace');
+    const result = [];
+    for (const workspace of workspaces) {
+        const id = encodeURIComponent(workspace.id);
+        const projects = await client.request('GET', `/project?workspaceId=${id}`);
+        // Attaching a label copies it for the task, so a name can occur many times.
+        const labelRows = await client.request('GET', `/label/workspace/${id}`);
+        const labels = [...new Set(labelRows.map((label) => label.name))].sort((a, b) => a.localeCompare(b));
+        for (const project of projects) {
+            const columns = await client.request('GET', `/column/${encodeURIComponent(project.id)}`);
+            result.push({
+                id: project.id,
+                name: project.name,
+                identifier: project.slug,
+                workspace: workspace.name,
+                states: [...columns].sort((a, b) => a.position - b.position).map((column) => column.name),
+                labels,
+            });
+        }
+    }
+    return result.sort((a, b) => a.workspace.localeCompare(b.workspace) || a.name.localeCompare(b.name));
+}

package/dist/linear/browse.js

@@ -0,0 +1,55 @@
+// Bounds a listing against a runaway cursor; 2000 matching issues is far outside normal use.
+const MAX_PAGES = 20;
+// Only conditions that were asked for are part of the query, so nothing is sent as "any".
+const issuesQuery = (filter) => `
+query BrowseIssues($teamId: ID!, $after: String${filter.projectId ? ', $projectId: ID!' : ''}${filter.states?.length ? ', $states: [String!]' : ''}) {
+  issues(
+    first: 100
+    after: $after
+    filter: {
+      team: { id: { eq: $teamId } }${filter.projectId ? '\n      project: { id: { eq: $projectId } }' : ''}${filter.states?.length ? '\n      state: { name: { in: $states } }' : ''}
+    }
+  ) {
+    nodes {
+      id identifier title description url priority createdAt
+      state { name }
+      labels { nodes { name } }
+      assignee { name }
+    }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+// "No priority" (0) sorts after "low" (4).
+const priorityRank = (priority) => (priority === 0 ? 5 : priority);
+/** Issues matching the filter, most urgent first. A read-only query; nothing in Linear changes. */
+export async function listIssues(client, filter) {
+    const query = issuesQuery(filter);
+    const tasks = [];
+    let after = null;
+    for (let page = 0; page < MAX_PAGES; page += 1) {
+        const data = await client.request(query, {
+            teamId: filter.teamId,
+            ...(filter.projectId ? { projectId: filter.projectId } : {}),
+            ...(filter.states?.length ? { states: filter.states } : {}),
+            after,
+        });
+        for (const node of data.issues.nodes) {
+            tasks.push({
+                id: node.id,
+                identifier: node.identifier,
+                title: node.title,
+                description: node.description,
+                url: node.url,
+                priority: node.priority,
+                status: node.state.name,
+                labels: node.labels.nodes.map((label) => label.name),
+                assignee: node.assignee?.name ?? null,
+                createdAt: node.createdAt,
+            });
+        }
+        if (!data.issues.pageInfo?.hasNextPage || !data.issues.pageInfo.endCursor)
+            break;
+        after = data.issues.pageInfo.endCursor;
+    }
+    return tasks.sort((a, b) => priorityRank(a.priority) - priorityRank(b.priority) || a.createdAt.localeCompare(b.createdAt));
+}