@kietdev/taiga-mcp 0.0.0-stage → 0.4.0

package/dist/taiga/http.js

@@ -0,0 +1,237 @@
+/** A failed call to Taiga, worded so that the model (and the person reading its answer) can act on it. */
+export class TaigaError extends Error {
+    status;
+    name = 'TaigaError';
+    constructor(message, 
+    /** HTTP status, when Taiga answered at all. */
+    status) {
+        super(message);
+        this.status = status;
+    }
+}
+const TIMEOUT_MS = 15_000;
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+const megabytes = (bytes) => `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+/** `size` is what was seen so far, so it may be less than the whole file. */
+const tooLarge = (size, max) => `The file is at least ${megabytes(size)}; this server reads files up to ${megabytes(max)}. Open it in Taiga instead.`;
+/**
+ * The only place that talks to Taiga. It signs in on first use, keeps the tokens in memory,
+ * and renews them once when Taiga answers 401. It sends GET requests, plus the two POSTs of the
+ * sign-in itself; POST and PATCH to create and change items only when the configuration allows
+ * writes. It has no way to send a DELETE.
+ */
+export class TaigaHttp {
+    #config;
+    #fetch;
+    #token;
+    #refreshToken;
+    /** A sign-in in flight, shared by the calls that are waiting for it. */
+    #signingIn;
+    constructor(config, fetchImpl = fetch) {
+        this.#config = config;
+        this.#fetch = fetchImpl;
+        this.#token = config.token;
+        this.#refreshToken = config.refreshToken;
+    }
+    /** One object, or a list that is known to be short (`everything` asks Taiga for all of it at once). */
+    async get(path, query = {}, options = {}) {
+        // Taiga pages lists by 30 unless told otherwise.
+        const headers = options.everything ? { 'x-disable-pagination': 'True' } : {};
+        const response = await this.#request('GET', path, query, headers);
+        return (await response.json());
+    }
+    /** Whether this connection may create and change items. */
+    get writable() {
+        return this.#config.write === true;
+    }
+    /** Create (POST) or change (PATCH) something, and read back what Taiga made of it. */
+    async write(method, path, body) {
+        // A second lock behind the tools: a read-only connection never sends a write, whatever calls it.
+        if (!this.writable) {
+            throw new TaigaError('This connection is read-only: changing Taiga is not switched on.', 403);
+        }
+        const response = await this.#request(method, path, {}, {}, body);
+        return (await response.json());
+    }
+    /**
+     * `limit` items of a list that may be long: the first ones, or those of a later `page`.
+     * Taiga reports the full count in a header.
+     */
+    async page(path, query, limit, page = 1) {
+        const paging = page > 1 ? { page_size: limit, page } : { page_size: limit };
+        let response;
+        try {
+            response = await this.#request('GET', path, { ...query, ...paging }, {});
+        }
+        catch (error) {
+            // Taiga answers 404 for a page after the last one.
+            if (page > 1 && error instanceof TaigaError && error.status === 404) {
+                throw new TaigaError(`The list has no page ${page} at ${limit} items a page. Call again with \`page\`: 1 to see how many items there are.`, 404);
+            }
+            throw error;
+        }
+        const items = (await response.json());
+        const count = Number(response.headers.get('x-pagination-count') ?? Number.NaN);
+        return { items, total: Number.isFinite(count) ? Math.max(count, items.length) : items.length };
+    }
+    /**
+     * A file Taiga stores, by the address Taiga gave for it. Those addresses carry their own
+     * signature, so no token is sent: the file server may be another host. Stops at `maxBytes`.
+     */
+    async download(url, maxBytes) {
+        let response;
+        try {
+            response = await this.#fetch(new URL(url), { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new TaigaError(`Could not download the file (${reason}).`);
+        }
+        if (!response.ok) {
+            throw new TaigaError(response.status === 403 || response.status === 401
+                ? 'Taiga refused the file. Its link may have expired: read the item again with get_item and retry.'
+                : `Taiga answered ${response.status} for the file.`, response.status);
+        }
+        const declared = Number(response.headers.get('content-length') ?? Number.NaN);
+        if (declared > maxBytes) {
+            await response.body?.cancel();
+            throw new TaigaError(tooLarge(declared, maxBytes), 413);
+        }
+        // The declared length may be missing or wrong: count while reading.
+        const chunks = [];
+        let size = 0;
+        const reader = response.body?.getReader();
+        while (reader !== undefined) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > maxBytes) {
+                await reader.cancel();
+                throw new TaigaError(tooLarge(size, maxBytes), 413);
+            }
+            chunks.push(value);
+        }
+        const bytes = new Uint8Array(size);
+        let at = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, at);
+            at += chunk.byteLength;
+        }
+        return { bytes, type: response.headers.get('content-type') ?? undefined };
+    }
+    /* ------------------------------ requests ------------------------------ */
+    async #request(method, path, query, headers, body) {
+        let response = await this.#send(path, query, { ...headers, ...this.#bearer(await this.#currentToken()) }, body, method);
+        if (response.status === 401) {
+            response = await this.#send(path, query, { ...headers, ...this.#bearer(await this.#renewToken()) }, body, method);
+        }
+        if (!response.ok)
+            throw await this.#failure(response, path, method);
+        return response;
+    }
+    #bearer(token) {
+        return { Authorization: `Bearer ${token}` };
+    }
+    async #send(path, query, headers, body, 
+    /** GET without a body; the sign-in sends its body with POST. */
+    method = body === undefined ? 'GET' : 'POST') {
+        const url = new URL(`${this.#config.baseUrl}/api/v1${path}`);
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        try {
+            return await this.#fetch(url, {
+                method,
+                headers: {
+                    Accept: 'application/json',
+                    ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                    ...headers,
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            if (method !== 'GET' && !path.startsWith('/auth')) {
+                // The request may have arrived even though no answer came back: do not invite a duplicate.
+                throw new TaigaError(`No answer from Taiga at ${this.#config.baseUrl} (${reason}). The change may or may not have been made: ` +
+                    'look at the item (or the list) before trying again.');
+            }
+            throw new TaigaError(`Could not reach Taiga at ${this.#config.baseUrl} (${reason}). Check TAIGA_URL.`);
+        }
+    }
+    async #failure(response, path, method) {
+        const { status } = response;
+        const verb = method === 'GET' ? 'read' : 'change';
+        if (status === 401) {
+            return new TaigaError('Taiga did not accept the sign-in. Check the credentials in the environment.', 401);
+        }
+        if (status === 403)
+            return new TaigaError(`The signed-in user may not ${verb} ${path} in Taiga.`, 403);
+        if (status === 404)
+            return new TaigaError(`Taiga has nothing at ${path}.`, 404);
+        if (status === 429)
+            return new TaigaError('Taiga is rate-limiting requests. Wait a moment and try again.', 429);
+        // Taiga explains most client errors in `_error_message`, and a rejected change field by field.
+        const detail = await response
+            .json()
+            .then(explain)
+            .catch(() => '');
+        return new TaigaError(`Taiga answered ${status} for ${path}${detail ? `: ${detail}` : ''}.`, status);
+    }
+    /* ------------------------------- sign-in ------------------------------- */
+    async #currentToken() {
+        return this.#token ?? this.#signIn();
+    }
+    /** After a 401: try the refresh token, then the username and password. */
+    async #renewToken() {
+        const refresh = this.#refreshToken;
+        this.#token = undefined;
+        if (refresh !== undefined) {
+            const response = await this.#send('/auth/refresh', {}, {}, { refresh });
+            if (response.ok)
+                return this.#remember((await response.json()));
+            this.#refreshToken = undefined;
+        }
+        return this.#signIn();
+    }
+    #signIn() {
+        this.#signingIn ??= this.#signInOnce().finally(() => {
+            this.#signingIn = undefined;
+        });
+        return this.#signingIn;
+    }
+    async #signInOnce() {
+        const { credentials } = this.#config;
+        if (credentials === undefined) {
+            throw new TaigaError(this.#config.expiredHint ??
+                'The Taiga token has expired and cannot be renewed. Set a new TAIGA_TOKEN, or set TAIGA_USERNAME and TAIGA_PASSWORD so the server can sign in by itself.', 401);
+        }
+        const response = await this.#send('/auth', {}, {}, { type: 'normal', ...credentials });
+        if (!response.ok) {
+            // Deliberately generic: the response body may repeat what was sent.
+            throw new TaigaError(`Taiga sign-in failed (${response.status}). Check TAIGA_USERNAME and TAIGA_PASSWORD.`, response.status);
+        }
+        return this.#remember((await response.json()));
+    }
+    #remember(auth) {
+        this.#token = auth.auth_token;
+        this.#refreshToken = auth.refresh;
+        return auth.auth_token;
+    }
+}
+/** Taiga's reason for refusing a request, in one line: its message, or each field and what is wrong. */
+function explain(data) {
+    if (typeof data !== 'object' || data === null)
+        return '';
+    if ('_error_message' in data)
+        return String(data._error_message);
+    return Object.entries(data)
+        .filter(([key]) => !key.startsWith('_'))
+        .map(([key, value]) => `${key}: ${Array.isArray(value) ? value.join(' ') : String(value)}`)
+        .join('; ');
+}
+//# sourceMappingURL=http.js.map

package/dist/taiga/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/taiga/http.ts"],"names":[],"mappings":"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"}

package/dist/taiga/types.js

@@ -0,0 +1,6 @@
+/**
+ * Taiga's API returns large objects. Only the fields this server reads are declared here
+ * ("Raw…"), and tools hand the model the trimmed shapes below them, never the raw response.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/taiga/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/taiga/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/tools/add-comment.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { answer } from '../format.js';
+import { ADDS, ONLY_WHEN_ASKED, project, ref } from './shared.js';
+import { written } from './written.js';
+export function registerAddComment(server, taiga) {
+    server.registerTool('add_comment', {
+        title: 'Comment on a story, issue, epic or task',
+        description: 'Post a comment on one user story, issue, epic or task of a Taiga project, by its reference ' +
+            'number, as the signed-in user. Project members are notified as Taiga does for any comment. ' +
+            `${ONLY_WHEN_ASKED} Unless the user dictated the text word for word, show it to them first. ` +
+            'Comments cannot be edited or removed from here.',
+        inputSchema: {
+            project,
+            ref,
+            text: z
+                .string()
+                .min(1)
+                .max(10_000)
+                .describe('The comment exactly as it should appear in Taiga. Markdown works.'),
+        },
+        annotations: ADDS,
+    }, answer(async (args) => written('Commented on', await taiga.addComment(args.project, args.ref, args.text))));
+}
+//# sourceMappingURL=add-comment.js.map

package/dist/tools/add-comment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-comment.js","sourceRoot":"","sources":["../../src/tools/add-comment.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,UAAU,kBAAkB,CAAC,MAAiB,EAAE,KAAkB;IACtE,MAAM,CAAC,YAAY,CACjB,aAAa,EACb;QACE,KAAK,EAAE,yCAAyC;QAChD,WAAW,EACT,6FAA6F;YAC7F,6FAA6F;YAC7F,GAAG,eAAe,2EAA2E;YAC7F,iDAAiD;QACnD,WAAW,EAAE;YACX,OAAO;YACP,GAAG;YACH,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,MAAM,CAAC;iBACX,QAAQ,CAAC,mEAAmE,CAAC;SACjF;QACD,WAAW,EAAE,IAAI;KAClB,EACD,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CACpB,OAAO,CAAC,cAAc,EAAE,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CACnF,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/create-item.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { answer } from '../format.js';
+import { ADDS, assignee, ONLY_WHEN_ASKED, project, subject, tags } from './shared.js';
+import { written } from './written.js';
+const name = (what) => z.string().min(1).max(200).optional().describe(what);
+export function registerCreateItem(server, taiga) {
+    server.registerTool('create_item', {
+        title: 'Create a user story, task or issue',
+        description: 'Create a user story, a task or an issue in a Taiga project, as the signed-in user. ' +
+            `${ONLY_WHEN_ASKED} Every name (status, person, sprint, story, epic, type…) is checked before ` +
+            'anything is created: a wrong one is answered with the valid names, and nothing is created. ' +
+            'The answer gives the new reference number. Call it once per item: if an answer is lost, look ' +
+            'for the item with search before creating it again.',
+        inputSchema: {
+            project,
+            kind: z
+                .enum(['story', 'task', 'issue'])
+                .describe('"story" for a user story, "task" for a task (usually of a story), "issue" for a bug or question.'),
+            subject: subject.describe('Title of the new item, short and specific.'),
+            description: z.string().max(50_000).optional().describe('Longer text for the item. Markdown works.'),
+            status: name('Status name as the project defines it for this kind of item (get_project lists them). Taiga’s default when left out.'),
+            assigned_to: assignee('Who will do it: a member’s full name or username (part of it is enough when it fits one member; accents may be left out), or "me". Nobody when left out.'),
+            tags: tags('Tags to put on the item, e.g. ["backend"].'),
+            sprint: name('Sprint name, "current" for the one running today, or "backlog" for none. Left out: a task joins the sprint of its story, a story or issue has none.'),
+            story: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('For a task: reference number of the user story it belongs to.'),
+            epic: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('For a user story: reference number of an epic to add it to.'),
+            due_date: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/, 'Use YYYY-MM-DD')
+                .optional()
+                .describe('Due date as YYYY-MM-DD.'),
+            type: name('For an issue: its type, e.g. "Bug". get_project lists the types.'),
+            severity: name('For an issue: its severity, e.g. "Critical".'),
+            priority: name('For an issue: its priority, e.g. "High".'),
+        },
+        annotations: ADDS,
+    }, answer(async (args) => written('Created', await taiga.createItem(args.project, {
+        kind: args.kind,
+        subject: args.subject,
+        description: args.description,
+        status: args.status,
+        assignedTo: args.assigned_to,
+        tags: args.tags,
+        sprint: args.sprint,
+        story: args.story,
+        epic: args.epic,
+        dueDate: args.due_date,
+        type: args.type,
+        severity: args.severity,
+        priority: args.priority,
+    }))));
+}
+//# sourceMappingURL=create-item.js.map

package/dist/tools/create-item.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-item.js","sourceRoot":"","sources":["../../src/tools/create-item.ts"],"names":[],"mappings":"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"}

package/dist/tools/file-view.js

@@ -0,0 +1,300 @@
+import { fold, plural } from '../format.js';
+import { TaigaError } from '../taiga/http.js';
+export const BUDGET = 20_000;
+const LINE_MAX = 2_000;
+const PREVIEW_ROWS = 10;
+const PREVIEW_LINES = 60;
+const OUTLINE_PAGES = 100;
+const FIRST_PAGE_MAX = 3_000;
+const clip = (line) => (line.length <= LINE_MAX ? line : `${line.slice(0, LINE_MAX)}… [line cut]`);
+/** "120-300", "120", "120-": the numbers asked for, both ends included. */
+export function parseRange(text, what) {
+    const match = /^\s*(\d+)\s*(?:[-–]\s*(\d*)\s*)?$/.exec(text);
+    if (match === null)
+        throw new TaigaError(`\`${what}\` takes numbers like "120-300", "5" or "40-"; not "${text}".`);
+    const from = Number(match[1]);
+    const to = match[2] === undefined ? from : match[2] === '' ? Number.POSITIVE_INFINITY : Number(match[2]);
+    if (from < 1 || to < from)
+        throw new TaigaError(`\`${what}\` "${text}" is not a range: it must count up from 1.`);
+    return { from, to };
+}
+/** Lines added one by one until the budget is spent; says where it stopped. */
+class Out {
+    lines = [];
+    #size = 0;
+    full = false;
+    add(line) {
+        const text = clip(line);
+        if (this.#size + text.length + 1 > BUDGET) {
+            this.full = true;
+            return false;
+        }
+        this.lines.push(text);
+        this.#size += text.length + 1;
+        return true;
+    }
+    get size() {
+        return this.#size;
+    }
+}
+const matcher = (find) => {
+    const words = fold(find).split(/\s+/).filter(Boolean);
+    return (text) => {
+        const folded = fold(text);
+        return words.every((word) => folded.includes(word));
+    };
+};
+export function view(content, selection) {
+    if (selection.sheet !== undefined && content.kind !== 'sheets') {
+        throw new TaigaError('`sheet` is for spreadsheets and CSV files. This file has no sheets.');
+    }
+    if (selection.pages !== undefined && content.kind !== 'pages') {
+        throw new TaigaError(`\`pages\` is for PDFs and presentations. ${content.kind === 'sheets' ? 'Use `sheet` and `rows`' : 'Use `rows` for lines'} here.`);
+    }
+    if (content.kind === 'sheets')
+        return viewSheets(content, selection);
+    if (content.kind === 'pages')
+        return viewPages(content, selection);
+    return viewLines(content, selection);
+}
+/* ---------------------------------- sheets ---------------------------------- */
+const rowText = (row) => `${row.n}: ${row.cells.join(' | ')}`;
+function pickSheets(sheets, wanted) {
+    if (wanted === undefined)
+        return sheets;
+    const byNumber = /^\d+$/.test(wanted.trim()) ? sheets[Number(wanted) - 1] : undefined;
+    const byName = sheets.find((sheet) => fold(sheet.name) === fold(wanted));
+    const found = byName ?? byNumber;
+    if (found === undefined) {
+        throw new TaigaError(`No sheet "${wanted}". Sheets: ${sheets.map((sheet, i) => `${i + 1}. "${sheet.name}"`).join(', ')}.`);
+    }
+    return [found];
+}
+function columns(sheet) {
+    return sheet.rows.reduce((max, row) => Math.max(max, row.cells.length), 0);
+}
+function viewSheets(content, selection) {
+    const sheets = pickSheets(content.sheets, selection.sheet);
+    const out = new Out();
+    const head = `Read as: ${content.from}. Each line is "row number: cells split by |".`;
+    if (selection.find !== undefined) {
+        const fits = matcher(selection.find);
+        let found = 0;
+        let shown = 0;
+        for (const sheet of sheets) {
+            for (const row of sheet.rows) {
+                if (!fits(row.cells.join(' ')))
+                    continue;
+                found++;
+                if (!out.full && out.add(`${sheets.length > 1 ? `"${sheet.name}" ` : ''}${rowText(row)}`))
+                    shown++;
+            }
+        }
+        return [
+            `${head}\nRows containing "${selection.find}": ${found}${shown < found ? `, the first ${shown} shown` : ''}.`,
+            out.lines.join('\n'),
+            shown < found ? 'Narrow `find` with more words, or pick a `sheet`.' : undefined,
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+    }
+    if (selection.rows !== undefined) {
+        if (sheets.length > 1) {
+            throw new TaigaError(`The file has ${sheets.length} sheets: name one with \`sheet\` (${sheets.map((s) => `"${s.name}"`).join(', ')}).`);
+        }
+        const [sheet] = sheets;
+        const { from, to } = parseRange(selection.rows, 'rows');
+        const header = sheet.rows[0];
+        const wanted = sheet.rows.filter((row) => row.n >= from && row.n <= to);
+        if (header !== undefined && header.n < from)
+            out.add(`(header) ${rowText(header)}`);
+        let last;
+        for (const row of wanted) {
+            if (!out.add(rowText(row)))
+                break;
+            last = row.n;
+        }
+        const lastInFile = sheet.rows.at(-1)?.n ?? 0;
+        const end = Number.isFinite(to) ? to : lastInFile;
+        // Rows asked for that did not fit in this answer.
+        const next = wanted.find((row) => last === undefined || row.n > last);
+        const more = next === undefined ? undefined : `Continue with \`rows\`: "${next.n}-${end}".`;
+        return [
+            `${head}\nSheet "${sheet.name}", rows ${from} to ${end}: ${wanted.length} with data${next === undefined ? '' : `, up to row ${last ?? from} shown`}.`,
+            out.lines.join('\n') || '(no rows with data here)',
+            more,
+            cutNote(sheet),
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+    }
+    // Everything, when it fits.
+    const whole = sheets.flatMap((sheet) => [`=== Sheet "${sheet.name}" ===`, ...sheet.rows.map(rowText), '']);
+    if (whole.every((line) => out.add(line)) &&
+        sheets.every((sheet) => sheet.rows.length === sheet.totalRows)) {
+        return `${head}\n\n${out.lines.join('\n').trim()}`;
+    }
+    // An overview, and how to read the rest.
+    const overview = sheets.map((sheet) => {
+        const preview = sheet.rows.slice(0, PREVIEW_ROWS).map(rowText);
+        return [
+            `=== Sheet "${sheet.name}": ${plural(sheet.totalRows, 'row')} with data, up to ${plural(columns(sheet), 'column')} ===`,
+            preview.length === 0 ? '(empty)' : preview.join('\n'),
+            sheet.rows.length > PREVIEW_ROWS ? `… ${sheet.totalRows - PREVIEW_ROWS} more rows` : undefined,
+            cutNote(sheet),
+        ]
+            .filter(Boolean)
+            .join('\n');
+    });
+    return [
+        `${head}\nToo large to show at once; this is an overview with the first ${PREVIEW_ROWS} rows of each sheet.`,
+        clipBudget(overview.join('\n\n')),
+        'To read more: `sheet` with `rows` (e.g. "11-300"), or `find` with words to get only the rows that contain them.',
+    ].join('\n\n');
+}
+const cutNote = (sheet) => sheet.rows.length < sheet.totalRows
+    ? `Only the first ${sheet.rows.length} of ${sheet.totalRows} rows of "${sheet.name}" can be read; use \`find\` to reach the rest.`
+    : undefined;
+const clipBudget = (text) => text.length <= BUDGET ? text : `${text.slice(0, BUDGET)}… [overview cut; pick a \`sheet\`]`;
+/* ---------------------------------- pages ---------------------------------- */
+function viewPages(content, selection) {
+    const { pages, unit, totalPages } = content;
+    const Unit = unit === 'page' ? 'Page' : 'Slide';
+    const out = new Out();
+    const head = `Read as: ${content.from}.`;
+    const unread = pages.length < totalPages ? `Pages after ${pages.length} cannot be read by this server.` : undefined;
+    if (selection.find !== undefined) {
+        const fits = matcher(selection.find);
+        let found = 0;
+        let shown = 0;
+        pages.forEach((page, i) => {
+            for (const line of page.split('\n')) {
+                if (!fits(line))
+                    continue;
+                found++;
+                if (!out.full && out.add(`${Unit} ${i + 1}: ${line.trim()}`))
+                    shown++;
+            }
+        });
+        return [
+            `${head}\nLines containing "${selection.find}": ${found}${shown < found ? `, the first ${shown} shown` : ''}.`,
+            out.lines.join('\n'),
+            found > 0 ? `Read a whole ${unit} with \`pages\`.` : undefined,
+            unread,
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+    }
+    const render = (from, to) => {
+        let last = from - 1;
+        for (let n = from; n <= Math.min(to, pages.length); n++) {
+            const block = [
+                `--- ${Unit} ${n} ---`,
+                ...(pages[n - 1] || `(no text on this ${unit}${unit === 'page' ? '; it may be a scan' : ''})`).split('\n'),
+            ];
+            // A page is shown whole or not at all, unless it alone is larger than the budget.
+            const fits = block.reduce((sum, line) => sum + clip(line).length + 1, 0) + out.size <= BUDGET;
+            if (!fits && last >= from)
+                break;
+            for (const line of block)
+                if (!out.add(line))
+                    break;
+            last = n;
+            if (out.full)
+                break;
+        }
+        return last;
+    };
+    if (selection.pages !== undefined) {
+        const { from, to } = parseRange(selection.pages, 'pages');
+        if (from > pages.length) {
+            throw new TaigaError(`The file has ${totalPages} ${unit}s${unread ? `, of which ${pages.length} can be read` : ''}.`);
+        }
+        const last = render(from, to);
+        const end = Math.min(to, pages.length);
+        return [
+            `${head}\n${Unit}s ${from} to ${last}${last < end ? ` of the ${from}-${end} asked for` : ''}.`,
+            out.lines.join('\n'),
+            last < end ? `Continue with \`pages\`: "${last + 1}-${end}".` : undefined,
+            unread,
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+    }
+    const total = pages.reduce((sum, page) => sum + page.length + 20, 0);
+    if (total <= BUDGET && pages.length === totalPages) {
+        render(1, pages.length);
+        return `${head}\n\n${out.lines.join('\n')}`;
+    }
+    const outline = pages
+        .slice(0, OUTLINE_PAGES)
+        .map((page, i) => `${Unit} ${i + 1}: ${(page.split('\n').find((line) => line.trim()) ?? '(no text)').slice(0, 80)}`);
+    const first = pages[0] ?? '';
+    return [
+        `${head}\nToo large to show at once; this is the first line of each ${unit}${pages.length > OUTLINE_PAGES ? ` (the first ${OUTLINE_PAGES})` : ''}, then ${Unit.toLowerCase()} 1.`,
+        outline.join('\n'),
+        `--- ${Unit} 1 ---\n${first.length > FIRST_PAGE_MAX ? `${first.slice(0, FIRST_PAGE_MAX)}… [${unit} cut]` : first || '(no text)'}`,
+        `To read more: \`pages\` (e.g. "2-6"), or \`find\` with words to get only the lines that contain them.`,
+        unread,
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+}
+/* ---------------------------------- lines ---------------------------------- */
+function viewLines(content, selection) {
+    const { lines } = content;
+    const out = new Out();
+    const head = `Read as: ${content.from}, ${lines.length} lines.`;
+    if (selection.find !== undefined) {
+        const fits = matcher(selection.find);
+        let found = 0;
+        let shown = 0;
+        lines.forEach((line, i) => {
+            if (!fits(line))
+                return;
+            found++;
+            if (!out.full && out.add(`${i + 1}: ${line}`))
+                shown++;
+        });
+        return [
+            `${head}\nLines containing "${selection.find}": ${found}${shown < found ? `, the first ${shown} shown` : ''}.`,
+            out.lines.join('\n'),
+            found > 0 ? 'Read the lines around one with `rows`.' : undefined,
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+    }
+    const render = (from, to) => {
+        let last = from - 1;
+        for (let n = from; n <= Math.min(to, lines.length); n++) {
+            if (!out.add(`${n}: ${lines[n - 1] ?? ''}`))
+                break;
+            last = n;
+        }
+        return last;
+    };
+    if (selection.rows !== undefined) {
+        const { from, to } = parseRange(selection.rows, 'rows');
+        if (from > lines.length)
+            throw new TaigaError(`The file has ${lines.length} lines.`);
+        const last = render(from, to);
+        const end = Math.min(to, lines.length);
+        return [
+            `${head}\nLines ${from} to ${last}.`,
+            out.lines.join('\n'),
+            last < end ? `Continue with \`rows\`: "${last + 1}-${end}".` : undefined,
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+    }
+    const total = lines.reduce((sum, line) => sum + clip(line).length + 1, 0);
+    if (total <= BUDGET)
+        return `${head}\n\n${lines.map(clip).join('\n')}`;
+    render(1, PREVIEW_LINES);
+    return [
+        `${head}\nToo large to show at once (${total} characters); these are the first ${out.lines.length} lines, numbered.`,
+        out.lines.join('\n'),
+        'To read more: `rows` for a range of lines (e.g. "61-400"), or `find` with words to get only the lines that contain them.',
+    ].join('\n\n');
+}
+//# sourceMappingURL=file-view.js.map