@martin4455/redmine-mcp-ro 0.3.0

package/dist/attachment-downloader.js

@@ -0,0 +1,190 @@
+import axios from 'axios';
+import { open, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { AttachmentParser } from './attachment-parser.js';
+import { createRedmineHttpClient, positiveInteger, requestLimits } from './http-client.js';
+import { safeErrorMessage } from './safe-error.js';
+import { downloadDirectory } from './download-directory.js';
+function attachmentFilename(value) {
+    // Check both path syntaxes even when running on Unix. Never silently strip directories.
+    if (typeof value !== 'string' || !value || value.startsWith('.') ||
+        /[\\/:\x00-\x1f\x7f]/.test(value) || /[. ]$/.test(value) ||
+        /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(value) ||
+        Buffer.byteLength(value) > 255) {
+        throw new Error('Unsafe attachment filename');
+    }
+    return value;
+}
+function responseFilename(response, fallback) {
+    const header = response.headers['content-disposition'];
+    if (typeof header === 'string') {
+        const extended = header.match(/filename\*\s*=\s*UTF-8''([^;]+)/i);
+        if (extended)
+            return attachmentFilename(decodeURIComponent(extended[1].trim()));
+        const match = header.match(/filename\s*=\s*(?:"([^"]*)"|([^;]*))/i);
+        if (match)
+            return attachmentFilename(match[1] ?? match[2].trim());
+    }
+    return attachmentFilename(fallback);
+}
+export class AttachmentDownloader {
+    config;
+    client;
+    parser = new AttachmentParser();
+    limits;
+    constructor(config) {
+        this.config = config;
+        this.client = createRedmineHttpClient(config);
+        this.limits = requestLimits(config);
+    }
+    async metadata(attachmentId) {
+        positiveInteger(attachmentId, 'attachmentId');
+        const response = await this.client.get(`/attachments/${attachmentId}.json`);
+        return response.data.attachment;
+    }
+    contentUrl(attachment) {
+        const url = attachment.content_url || attachment.href_url;
+        if (!url)
+            throw new Error('No content URL found for attachment');
+        // Root-relative content URLs belong to the server root, unlike API endpoint paths.
+        return new URL(url, `${this.config.url.replace(/\/+$/, '')}/`).href;
+    }
+    async downloadAttachment(attachmentId, outputDir, options = {}) {
+        positiveInteger(attachmentId, 'attachmentId');
+        if (options.timestamp !== undefined)
+            positiveInteger(options.timestamp, 'timestamp');
+        let attachment;
+        try {
+            await downloadDirectory(this.config.downloadDir, outputDir);
+            try {
+                attachment = await this.metadata(attachmentId);
+            }
+            catch (error) {
+                if (!axios.isAxiosError(error) || error.response?.status !== 404 || !(options.version || options.timestamp)) {
+                    throw error;
+                }
+                attachment = { id: attachmentId, filename: options.fallbackFilename || `attachment_${attachmentId}` };
+            }
+            let url;
+            if (options.version || options.timestamp) {
+                const params = new URLSearchParams();
+                if (options.version)
+                    params.set('version', 'true');
+                if (options.timestamp)
+                    params.set('t', String(options.timestamp));
+                url = `/attachments/${attachmentId}?${params}`;
+            }
+            else {
+                url = this.contentUrl(attachment);
+            }
+            const response = await this.client.get(url, {
+                responseType: 'stream',
+                maxContentLength: this.limits.maxAttachmentBytes,
+            });
+            // A stream can fail while the filesystem is being prepared, before pipeline attaches.
+            response.data.once('error', () => { });
+            try {
+                const filename = responseFilename(response, attachment.filename);
+                const declaredSize = Number(response.headers['content-length']);
+                if (declaredSize > this.limits.maxAttachmentBytes)
+                    throw new Error('Attachment exceeds the download size limit');
+                return await this.saveFile(response.data, filename, outputDir, attachment.content_type);
+            }
+            finally {
+                // Also stop a response rejected before a writer was opened (unsafe name, collision, etc.).
+                response.data.destroy();
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to download attachment ${attachmentId}: ${safeErrorMessage(error, [this.config.apiKey])}`);
+        }
+    }
+    async saveFile(stream, filename, outputDir, contentType) {
+        const directory = await downloadDirectory(this.config.downloadDir, outputDir, true);
+        const filepath = path.join(directory, filename);
+        if (path.dirname(filepath) !== directory)
+            throw new Error('Attachment path is outside the output directory');
+        // Exclusive creation rejects existing files and symlinks, including dangling ones.
+        const handle = await open(filepath, 'wx', 0o600);
+        let size = 0;
+        const maxBytes = this.limits.maxAttachmentBytes;
+        const limit = new Transform({
+            transform(chunk, _encoding, callback) {
+                size += chunk.byteLength;
+                callback(size > maxBytes ? new Error('Attachment exceeds the download size limit') : null, chunk);
+            },
+        });
+        try {
+            await pipeline(stream, limit, handle.createWriteStream());
+            return { filepath, filename, size, content_type: contentType };
+        }
+        catch (error) {
+            await handle.close().catch(() => { });
+            // Only a file exclusively created by this download is ever removed.
+            await unlink(filepath).catch(() => { });
+            throw error;
+        }
+        finally {
+            await handle.close().catch(() => { });
+        }
+    }
+    async downloadIssueAttachments(issueId, outputDir) {
+        return this.downloadAllIssueAttachments(issueId, outputDir, false);
+    }
+    async downloadAllIssueAttachments(issueId, outputDir, includeEmbedded = true) {
+        positiveInteger(issueId, 'issueId');
+        try {
+            await downloadDirectory(this.config.downloadDir, outputDir);
+            const response = await this.client.get(`/issues/${issueId}.json`, {
+                params: { include: includeEmbedded ? 'attachments,journals' : 'attachments' },
+            });
+            const issue = response.data.issue;
+            const allAttachments = this.parser.findAllAttachments(includeEmbedded ? issue : { attachments: issue.attachments }, this.config.url);
+            const results = [];
+            for (const attachment of allAttachments) {
+                try {
+                    const result = await this.downloadAttachment(attachment.id, outputDir, {
+                        version: attachment.version,
+                        timestamp: attachment.timestamp,
+                        fallbackFilename: attachment.filename || `attachment_${attachment.id}`,
+                    });
+                    results.push({
+                        ...result,
+                        attachment_id: attachment.id,
+                        source: issue.attachments?.some(a => a.id === attachment.id) ? 'api' : 'embedded',
+                    });
+                }
+                catch (error) {
+                    console.error(`Failed to download attachment ${attachment.id}: ${safeErrorMessage(error, [this.config.apiKey])}`);
+                }
+            }
+            return results;
+        }
+        catch (error) {
+            throw new Error(`Failed to get issue attachments: ${safeErrorMessage(error, [this.config.apiKey])}`);
+        }
+    }
+    async getAttachmentContent(attachmentId) {
+        try {
+            const attachment = await this.metadata(attachmentId);
+            const response = await this.client.get(this.contentUrl(attachment), {
+                responseType: 'arraybuffer',
+                maxContentLength: this.limits.maxContentBytes,
+            });
+            const buffer = Buffer.from(response.data);
+            if (buffer.byteLength > this.limits.maxContentBytes)
+                throw new Error('Attachment exceeds the in-memory size limit');
+            return {
+                filename: attachment.filename,
+                content: buffer.toString('base64'),
+                content_type: attachment.content_type,
+                size: buffer.byteLength,
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to get attachment content: ${safeErrorMessage(error, [this.config.apiKey])}`);
+        }
+    }
+}

package/dist/attachment-parser.d.ts

@@ -0,0 +1,27 @@
+import type { AttachmentIssue, ParsedAttachment } from './types.js';
+export type { ParsedAttachment } from './types.js';
+/**
+ * Parser to extract attachment references from HTML content
+ */
+export declare class AttachmentParser {
+    /**
+     * Parse HTML content to find attachment links
+     * @param html - HTML content to parse
+     * @param baseUrl - Base URL of the Redmine instance
+     * @returns Array of parsed attachment information
+     */
+    parseHtml(html: string, baseUrl: string): ParsedAttachment[];
+    /**
+     * Parse issue data to find all embedded attachments
+     * @param issue - Issue data from Redmine API
+     * @param baseUrl - Base URL of the Redmine instance
+     * @returns Array of all attachments (API + embedded)
+     */
+    findAllAttachments(issue: AttachmentIssue, baseUrl: string): ParsedAttachment[];
+    /**
+     * Extract attachment IDs from HTML content
+     * @param html - HTML content to parse
+     * @returns Array of attachment IDs
+     */
+    extractAttachmentIds(html: string): number[];
+}

package/dist/attachment-parser.js

@@ -0,0 +1,138 @@
+import { JSDOM, VirtualConsole } from 'jsdom';
+/**
+ * Parser to extract attachment references from HTML content
+ */
+export class AttachmentParser {
+    /**
+     * Parse HTML content to find attachment links
+     * @param html - HTML content to parse
+     * @param baseUrl - Base URL of the Redmine instance
+     * @returns Array of parsed attachment information
+     */
+    parseHtml(html, baseUrl) {
+        if (!html)
+            return [];
+        let base;
+        try {
+            base = new URL(baseUrl);
+        }
+        catch {
+            return [];
+        }
+        if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password)
+            return [];
+        const attachments = [];
+        const ids = new Set();
+        // Scripts and resource loading stay disabled. Do not forward parser diagnostics:
+        // jsdom errors can include private document content, such as malformed CSS.
+        const dom = new JSDOM(html, { virtualConsole: new VirtualConsole() });
+        try {
+            const document = dom.window.document;
+            // Find all links that point to attachments
+            const links = document.querySelectorAll('a[href*="/attachments/"]');
+            links.forEach((link) => {
+                const href = link.getAttribute('href');
+                if (!href)
+                    return;
+                // Parse attachment URL patterns:
+                // - /attachments/123
+                // - /attachments/123/filename.ext
+                // - /attachments/download/123/filename.ext
+                // - https://redmine.example.com/attachments/123?t=1700000000&version=true
+                // Inspect the resolved URL, not query/fragment text that resembles a path.
+                let url;
+                try {
+                    url = new URL(href, base);
+                }
+                catch {
+                    return;
+                }
+                if (url.origin !== base.origin || url.username || url.password ||
+                    !['http:', 'https:'].includes(url.protocol))
+                    return;
+                const attachmentMatch = url.pathname.match(/\/attachments\/(?:download\/)?(\d+)(?:\/|$)/);
+                if (!attachmentMatch)
+                    return;
+                const attachmentId = Number(attachmentMatch[1]);
+                const filename = link.textContent?.trim() || '';
+                // Parse URL parameters
+                const timestamp = url.searchParams.get('t');
+                const parsedTimestamp = timestamp === null ? undefined : Number(timestamp);
+                const version = url.searchParams.get('version') === 'true';
+                // Avoid duplicates
+                if (Number.isSafeInteger(attachmentId) && attachmentId > 0 && !ids.has(attachmentId)) {
+                    ids.add(attachmentId);
+                    attachments.push({
+                        id: attachmentId,
+                        filename,
+                        url: href,
+                        timestamp: parsedTimestamp !== undefined && Number.isSafeInteger(parsedTimestamp) && parsedTimestamp > 0
+                            ? parsedTimestamp : undefined,
+                        version: version || undefined,
+                    });
+                }
+            });
+            return attachments;
+        }
+        finally {
+            dom.window.close();
+        }
+    }
+    /**
+     * Parse issue data to find all embedded attachments
+     * @param issue - Issue data from Redmine API
+     * @param baseUrl - Base URL of the Redmine instance
+     * @returns Array of all attachments (API + embedded)
+     */
+    findAllAttachments(issue, baseUrl) {
+        const attachments = [];
+        const processedIds = new Set();
+        // First, add attachments from the API response
+        if (issue.attachments && Array.isArray(issue.attachments)) {
+            issue.attachments.forEach((attachment) => {
+                if (!processedIds.has(attachment.id)) {
+                    attachments.push({
+                        id: attachment.id,
+                        filename: attachment.filename,
+                        url: attachment.content_url || attachment.href_url || '',
+                    });
+                    processedIds.add(attachment.id);
+                }
+            });
+        }
+        // Parse description for embedded attachments
+        if (issue.description) {
+            const descAttachments = this.parseHtml(issue.description, baseUrl);
+            descAttachments.forEach(att => {
+                if (!processedIds.has(att.id)) {
+                    attachments.push(att);
+                    processedIds.add(att.id);
+                }
+            });
+        }
+        // Parse journals/comments for embedded attachments
+        if (issue.journals && Array.isArray(issue.journals)) {
+            issue.journals.forEach((journal) => {
+                if (journal.notes) {
+                    const journalAttachments = this.parseHtml(journal.notes, baseUrl);
+                    journalAttachments.forEach(att => {
+                        if (!processedIds.has(att.id)) {
+                            attachments.push(att);
+                            processedIds.add(att.id);
+                        }
+                    });
+                }
+            });
+        }
+        return attachments;
+    }
+    /**
+     * Extract attachment IDs from HTML content
+     * @param html - HTML content to parse
+     * @returns Array of attachment IDs
+     */
+    extractAttachmentIds(html) {
+        const attachments = this.parseHtml(html, 'https://example.com');
+        return attachments.map(a => a.id);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { createRedmineHttpClient, redmineBaseUrl } from './http-client.js';
+import { safeErrorMessage } from './safe-error.js';
+import { ConfigurationError, validateProfileName } from './config-file.js';
+import { LocalConfiguration, readConnection, validateApiKey } from './local-configuration.js';
+import { CredentialStoreUnavailableError } from './credential-store.js';
+import { ConfigLoader } from './config-loader.js';
+const local = (options) => new LocalConfiguration({ directory: options.configDir });
+function display(config) {
+    for (const [name, profile] of Object.entries(config?.profiles ?? {})) {
+        console.log(`  ${name}${config?.defaultProfile === name ? ' (default)' : ''}`);
+        console.log(`    Credential ID: ${profile.credentialId}`);
+    }
+}
+function report(change, message) {
+    console.log(chalk.green(message));
+    for (const { from, to } of change.profileRenames ?? []) {
+        // Legacy names may contain terminal control characters. Never print them literally.
+        const escaped = JSON.stringify(from).replace(/[\u0080-\uffff]/g, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
+        console.log(`Renamed profile ${escaped} -> ${JSON.stringify(to)}. Update REDMINE_PROFILE or --profile if used.`);
+    }
+    for (const warning of change.warnings)
+        console.error(chalk.yellow(warning));
+    if (change.warnings.length)
+        process.exitCode = 1;
+}
+async function configure(options) {
+    const manager = local(options);
+    const current = manager.read();
+    console.log(`Configuring ${manager.configPath}`);
+    const { profileName } = await inquirer.prompt([
+        {
+            type: 'input', name: 'profileName', message: 'Profile name:', default: options.profile ?? 'default',
+            validate: (value) => { try {
+                validateProfileName(value);
+                return true;
+            }
+            catch {
+                return 'Use a short profile name containing letters, numbers, dots, underscores or hyphens.';
+            } },
+        },
+    ]);
+    let previous;
+    if (current?.profiles[profileName]) {
+        try {
+            previous = await readConnection(manager.store, current.profiles[profileName]);
+        }
+        catch (error) {
+            if (error instanceof CredentialStoreUnavailableError)
+                throw error;
+            console.log('The existing connection is missing or invalid. Enter complete connection details to replace it.');
+        }
+    }
+    const answers = await inquirer.prompt([
+        {
+            type: 'input', name: 'url', message: 'Redmine URL:',
+            default: previous?.url ?? 'https://redmine.example.com',
+            validate: (value) => { try {
+                redmineBaseUrl(value);
+                return true;
+            }
+            catch {
+                return 'Enter an HTTP(S) URL without credentials, a query or a fragment.';
+            } },
+        },
+        {
+            type: 'password', name: 'apiKey', message: 'API key (saved in the system credential store):', mask: '*',
+            validate: (value) => { try {
+                validateApiKey(value);
+                return true;
+            }
+            catch {
+                return 'Enter a nonempty API key without surrounding whitespace or line breaks.';
+            } },
+        },
+        { type: 'confirm', name: 'testConnection', message: 'Test connection?', default: true },
+    ]);
+    if (answers.testConnection) {
+        try {
+            const client = createRedmineHttpClient({ url: answers.url, apiKey: answers.apiKey, requestTimeoutMs: 5000 });
+            await client.get('/users/current.json');
+            console.log(chalk.green('Connection successful.'));
+        }
+        catch (error) {
+            console.error(chalk.yellow(safeErrorMessage(error, [answers.apiKey, answers.url])));
+            const answer = await inquirer.prompt([{ type: 'confirm', name: 'save', message: 'Save configuration anyway?', default: false }]);
+            if (!answer.save)
+                return;
+        }
+    }
+    report(await manager.configure(profileName, answers.url, answers.apiKey), `Profile reference saved to ${manager.configPath}. URL and API key stored together in the system credential store.`);
+}
+const program = new Command().name('redmine-mcp').description('Configure local Redmine profiles using the system credential store').version('0.3.0');
+const command = (name, description) => program.command(name).description(description)
+    .option('-d, --config-dir <directory>', 'Directory containing .redmine-mcp (default: REDMINE_CONFIG_DIR or current directory)');
+command('configure', 'Save the connection JSON in the system credential store')
+    .option('-p, --profile <name>', 'Profile name', 'default')
+    .action(configure);
+command('migrate', 'Upgrade version 1.0/2.0 files to references with the complete connection in the system store')
+    .action(async (options) => {
+    const manager = local(options);
+    report(await manager.migrate(), `Configuration ready at ${manager.configPath}; no URLs or API keys in this file.`);
+});
+command('list', 'List profiles in the selected directory without accessing their tokens')
+    .action((options) => {
+    const manager = local(options);
+    console.log(`Configuration: ${manager.configPath}`);
+    const config = manager.read();
+    if (!config || !Object.keys(config.profiles).length)
+        console.log('No local profiles. Run redmine-mcp configure.');
+    else
+        display(config);
+});
+command('status', 'Check the selected local profile and its system credential')
+    .option('-p, --profile <name>', 'Profile to check')
+    .action(async (options) => {
+    const config = await new ConfigLoader({ directory: options.configDir, profile: options.profile }).getConfig();
+    if (!config)
+        throw new ConfigurationError('No local configuration. Run redmine-mcp configure --config-dir <directory>.');
+    console.log(`Configuration: ${config.source}\nProfile: ${config.profile}\nCredential: available in system store`);
+});
+command('use <profile>', 'Select the default profile in this local configuration')
+    .action(async (profile, options) => {
+    await local(options).useProfile(profile);
+    console.log(chalk.green(`Default profile: ${profile}`));
+});
+command('remove <profile>', 'Remove a local profile and its system credential')
+    .option('-y, --yes', 'Do not prompt for confirmation')
+    .action(async (profile, options) => {
+    validateProfileName(profile);
+    if (!options.yes) {
+        const answer = await inquirer.prompt([{ type: 'confirm', name: 'remove', message: `Remove profile ${profile} and its stored token?`, default: false }]);
+        if (!answer.remove)
+            return;
+    }
+    report(await local(options).remove(profile), `Removed profile: ${profile}`);
+});
+program.parseAsync().catch(error => {
+    console.error(chalk.red(error instanceof ConfigurationError ? error.message : 'Configuration failed. Check the selected directory and system credential store.'));
+    process.exitCode = 1;
+});

package/dist/config-file.d.ts

@@ -0,0 +1,18 @@
+import type { ConfigFile, StoredConfigFile } from './types.js';
+export declare const CONFIG_FILENAME = ".redmine-mcp";
+export declare const CREDENTIAL_ID: RegExp;
+export declare class ConfigurationError extends Error {
+}
+export declare function normalizeRedmineUrl(value: string): string;
+export declare function validateProfileName(value: string): void;
+export declare function parseConfig(raw: string): StoredConfigFile;
+export interface ConfigSnapshot {
+    raw: string | null;
+    config: StoredConfigFile | null;
+}
+export declare function readConfig(configPath: string): ConfigSnapshot;
+export declare function requireModern(config: StoredConfigFile | null): ConfigFile;
+/** Atomic replacement; temporary files contain validated, secret-free metadata only. */
+export declare function writeConfig(configPath: string, config: ConfigFile, expectedRaw: string | null): void;
+export declare function withConfigLock<T>(configPath: string, action: () => Promise<T>): Promise<T>;
+export declare function localConfigPath(directory?: string): string;