@elyracode/youtrack 0.8.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [0.8.1] - 2026-05-27
+
+### Added
+- Initial release with 18 YouTrack tools covering issues, comments, tags, links, projects, users, articles, and time tracking
+- `elyra-youtrack` skill for YouTrack query syntax and workflow guidance

package/README.md

@@ -0,0 +1,50 @@
+# @elyracode/youtrack
+
+YouTrack integration for Elyra. Search issues, manage assignments, add comments, track time, browse projects and articles, and more -- all from within your Elyra session.
+
+## Install
+
+```
+elyra install npm:@elyracode/youtrack
+```
+
+## Configuration
+
+Set the following environment variables (or add them to your `.env` file):
+
+| Variable | Description |
+|----------|-------------|
+| `YOUTRACK_BASE_URL` | Your YouTrack instance URL (e.g. `https://myteam.youtrack.cloud`) |
+| `YOUTRACK_TOKEN` | Permanent token from YouTrack (Profile > Authentication > New Token) |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `youtrack_search_issues` | Search issues using YouTrack query syntax |
+| `youtrack_get_issue` | Get full details of a single issue by ID |
+| `youtrack_create_issue` | Create a new issue in a project |
+| `youtrack_update_issue` | Update fields on an existing issue |
+| `youtrack_delete_issue` | Delete an issue |
+| `youtrack_list_comments` | List comments on an issue |
+| `youtrack_add_comment` | Add a comment to an issue |
+| `youtrack_list_tags` | List available tags |
+| `youtrack_apply_tag` | Apply or remove a tag on an issue |
+| `youtrack_list_links` | List links on an issue (duplicates, subtasks, related) |
+| `youtrack_add_link` | Add a link between two issues |
+| `youtrack_list_projects` | List all accessible projects |
+| `youtrack_get_project` | Get project details and custom field schema |
+| `youtrack_list_users` | List users in the YouTrack instance |
+| `youtrack_get_current_user` | Get the authenticated user's profile |
+| `youtrack_search_articles` | Search knowledge base articles |
+| `youtrack_get_article` | Get a knowledge base article by ID |
+| `youtrack_add_work_item` | Add a time tracking work item to an issue |
+
+## Skill
+
+This package includes the `elyra-youtrack` skill, which provides the agent with YouTrack query syntax reference and workflow guidance. It is loaded automatically when the extension is installed.
+
+## Requirements
+
+- A YouTrack instance (Cloud or self-hosted)
+- A permanent token with appropriate permissions

package/extensions/index.ts

@@ -0,0 +1,717 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { Type } from "typebox";
+
+// ── Configuration ───────────────────────────────────────────────────────────
+
+interface YouTrackConfig {
+	baseUrl: string;
+	token: string;
+}
+
+function loadEnv(cwd: string): Record<string, string> {
+	const envPath = join(cwd, ".env");
+	if (!existsSync(envPath)) return {};
+	const result: Record<string, string> = {};
+	for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const eq = trimmed.indexOf("=");
+		if (eq < 0) continue;
+		const key = trimmed.slice(0, eq).trim();
+		let value = trimmed.slice(eq + 1).trim();
+		if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+			value = value.slice(1, -1);
+		}
+		result[key] = value;
+	}
+	return result;
+}
+
+function getConfig(cwd: string): YouTrackConfig | null {
+	const env = loadEnv(cwd);
+	const baseUrl = process.env.YOUTRACK_BASE_URL || env.YOUTRACK_BASE_URL;
+	const token = process.env.YOUTRACK_TOKEN || env.YOUTRACK_TOKEN;
+	if (!baseUrl || !token) return null;
+	return { baseUrl: baseUrl.replace(/\/+$/, ""), token };
+}
+
+// ── HTTP Client ─────────────────────────────────────────────────────────────
+
+async function ytFetch(
+	config: YouTrackConfig,
+	method: string,
+	path: string,
+	body?: unknown,
+): Promise<{ ok: boolean; status: number; data: unknown; text: string }> {
+	const url = `${config.baseUrl}${path}`;
+	const headers: Record<string, string> = {
+		Authorization: `Bearer ${config.token}`,
+		Accept: "application/json",
+	};
+	if (body !== undefined) {
+		headers["Content-Type"] = "application/json";
+	}
+	const response = await fetch(url, {
+		method,
+		headers,
+		body: body !== undefined ? JSON.stringify(body) : undefined,
+		signal: AbortSignal.timeout(30_000),
+	});
+	const text = await response.text();
+	let data: unknown;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		data = text;
+	}
+	return { ok: response.ok, status: response.status, data, text };
+}
+
+function ok(text: string) {
+	return { content: [{ type: "text" as const, text }] };
+}
+
+function err(text: string) {
+	return { content: [{ type: "text" as const, text }], isError: true as const };
+}
+
+function noConfig() {
+	return err("YouTrack not configured. Set YOUTRACK_BASE_URL and YOUTRACK_TOKEN in environment or .env file.");
+}
+
+// ── Formatters ──────────────────────────────────────────────────────────────
+
+function formatTimestamp(ms: number | null | undefined): string {
+	if (!ms) return "—";
+	return new Date(ms).toISOString().replace("T", " ").replace(/\.\d+Z$/, " UTC");
+}
+
+function formatCustomFields(fields: Array<{ name?: string; value?: unknown }>): string {
+	if (!fields || fields.length === 0) return "";
+	const lines: string[] = [];
+	for (const f of fields) {
+		const name = f.name ?? "unknown";
+		const val = f.value;
+		if (val === null || val === undefined) {
+			lines.push(`  ${name}: —`);
+		} else if (Array.isArray(val)) {
+			const names = val.map((v: { name?: string; login?: string }) => v.name || v.login || "?").join(", ");
+			lines.push(`  ${name}: ${names}`);
+		} else if (typeof val === "object" && val !== null) {
+			const v = val as { name?: string; login?: string; fullName?: string; minutes?: number };
+			lines.push(`  ${name}: ${v.name || v.fullName || v.login || JSON.stringify(val)}`);
+		} else {
+			lines.push(`  ${name}: ${String(val)}`);
+		}
+	}
+	return lines.join("\n");
+}
+
+function formatIssue(issue: Record<string, unknown>): string {
+	const lines: string[] = [];
+	const id = issue.idReadable || issue.id || "?";
+	const summary = issue.summary || "(no summary)";
+	lines.push(`${id}: ${summary}`);
+	if (issue.description) lines.push(`Description: ${String(issue.description).slice(0, 500)}`);
+	if (issue.project) {
+		const p = issue.project as { name?: string; shortName?: string };
+		lines.push(`Project: ${p.name || p.shortName || "?"}`);
+	}
+	if (issue.reporter) {
+		const r = issue.reporter as { login?: string; fullName?: string };
+		lines.push(`Reporter: ${r.fullName || r.login || "?"}`);
+	}
+	const created = issue.created as number | undefined;
+	const updated = issue.updated as number | undefined;
+	const resolved = issue.resolved as number | undefined;
+	if (created) lines.push(`Created: ${formatTimestamp(created)}`);
+	if (updated) lines.push(`Updated: ${formatTimestamp(updated)}`);
+	if (resolved) lines.push(`Resolved: ${formatTimestamp(resolved)}`);
+	if (issue.tags) {
+		const tags = issue.tags as Array<{ name?: string }>;
+		if (tags.length > 0) lines.push(`Tags: ${tags.map((t) => t.name || "?").join(", ")}`);
+	}
+	if (issue.votes !== undefined) lines.push(`Votes: ${issue.votes}`);
+	const cf = issue.customFields as Array<{ name?: string; value?: unknown }> | undefined;
+	if (cf && cf.length > 0) {
+		lines.push("Custom Fields:");
+		lines.push(formatCustomFields(cf));
+	}
+	return lines.join("\n");
+}
+
+function formatIssueList(issues: Array<Record<string, unknown>>): string {
+	if (issues.length === 0) return "No issues found.";
+	const lines: string[] = [`${issues.length} issue(s):\n`];
+	for (const issue of issues) {
+		const id = issue.idReadable || issue.id || "?";
+		const summary = issue.summary || "(no summary)";
+		const cf = issue.customFields as Array<{ name?: string; value?: unknown }> | undefined;
+		let state = "";
+		let assignee = "";
+		let priority = "";
+		if (cf) {
+			for (const f of cf) {
+				const val = f.value as { name?: string; login?: string; fullName?: string } | null;
+				if (!val) continue;
+				if (f.name === "State") state = val.name || "";
+				if (f.name === "Assignee") assignee = val.fullName || val.login || val.name || "";
+				if (f.name === "Priority") priority = val.name || "";
+			}
+		}
+		const parts = [String(id), String(summary)];
+		if (state) parts.push(`[${state}]`);
+		if (priority) parts.push(`P:${priority}`);
+		if (assignee) parts.push(`@${assignee}`);
+		const resolved = issue.resolved as number | null | undefined;
+		if (resolved) parts.push("(resolved)");
+		lines.push(parts.join("  "));
+	}
+	return lines.join("\n");
+}
+
+// ── Extension ───────────────────────────────────────────────────────────────
+
+export default function (elyra: ExtensionAPI): void {
+	let cwd = "";
+
+	elyra.on("session_start", async (_event, ctx) => {
+		cwd = ctx.cwd;
+	});
+
+	const getCwd = () => cwd;
+
+	const ISSUE_FIELDS = "id,idReadable,summary,description,project(id,name,shortName),reporter(login,fullName),created,updated,resolved,tags(id,name),votes,customFields(id,name,projectCustomField(field(name)),value(id,name,login,fullName,minutes))";
+	const ISSUE_LIST_FIELDS = "id,idReadable,summary,resolved,customFields(name,value(name,login,fullName))";
+
+	// ── youtrack_search_issues ───────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_search_issues",
+		label: "YouTrack Search",
+		description:
+			"Search for issues using YouTrack query language. Supports filters like 'for: me', '#Unresolved', 'project: {Name}', 'Priority: Critical', 'Type: Bug', and free text. Returns issue ID, summary, state, assignee, and priority.",
+		parameters: Type.Object({
+			query: Type.String({ description: "YouTrack search query (e.g. 'for: me #Unresolved', 'project: Backend Type: Bug')" }),
+			limit: Type.Optional(Type.Integer({ description: "Max results to return. Default 25, max 100." })),
+			offset: Type.Optional(Type.Integer({ description: "Number of results to skip for pagination." })),
+		}),
+		promptSnippet: "Search YouTrack issues",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const top = Math.min(params.limit ?? 25, 100);
+			const skip = params.offset ?? 0;
+			const q = encodeURIComponent(params.query);
+			const res = await ytFetch(config, "GET", `/api/issues?fields=${ISSUE_LIST_FIELDS}&query=${q}&$top=${top}&$skip=${skip}`);
+			if (!res.ok) return err(`Search failed (${res.status}): ${res.text}`);
+			return ok(formatIssueList(res.data as Array<Record<string, unknown>>));
+		},
+	});
+
+	// ── youtrack_get_issue ───────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_get_issue",
+		label: "YouTrack Get Issue",
+		description:
+			"Get full details for a specific issue including summary, description, custom fields, reporter, tags, and votes. Use the readable issue ID (e.g. 'PROJ-123').",
+		parameters: Type.Object({
+			issue_id: Type.String({ description: "Issue ID (e.g. 'PROJ-123')" }),
+		}),
+		promptSnippet: "Get YouTrack issue details",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const res = await ytFetch(config, "GET", `/api/issues/${encodeURIComponent(params.issue_id)}?fields=${ISSUE_FIELDS}`);
+			if (!res.ok) return err(`Failed to get issue (${res.status}): ${res.text}`);
+			return ok(formatIssue(res.data as Record<string, unknown>));
+		},
+	});
+
+	// ── youtrack_create_issue ────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_create_issue",
+		label: "YouTrack Create Issue",
+		description:
+			"Create a new issue in a project. Requires project ID and summary. Use youtrack_get_issue_fields_schema first to discover required custom fields and valid values.",
+		parameters: Type.Object({
+			project_id: Type.String({ description: "Project database ID (e.g. '0-3'). Use youtrack_find_projects to discover IDs." }),
+			summary: Type.String({ description: "Issue summary/title" }),
+			description: Type.Optional(Type.String({ description: "Issue description (supports Markdown)" })),
+			custom_fields: Type.Optional(Type.Array(
+				Type.Object({
+					name: Type.String({ description: "Custom field name (e.g. 'Priority', 'Type', 'State')" }),
+					value: Type.Unknown({ description: "Field value — object like {name: 'Critical'} or array for multi-value fields" }),
+					$type: Type.Optional(Type.String({ description: "Field type (e.g. 'SingleEnumIssueCustomField'). Get from schema." })),
+				}),
+				{ description: "Custom field values. Use youtrack_get_issue_fields_schema to discover valid fields and values." },
+			)),
+		}),
+		promptSnippet: "Create a YouTrack issue",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const body: Record<string, unknown> = {
+				summary: params.summary,
+				project: { id: params.project_id },
+			};
+			if (params.description) body.description = params.description;
+			if (params.custom_fields) body.customFields = params.custom_fields;
+			const res = await ytFetch(config, "POST", `/api/issues?fields=idReadable,id`, body);
+			if (!res.ok) return err(`Failed to create issue (${res.status}): ${res.text}`);
+			const data = res.data as { idReadable?: string; id?: string };
+			return ok(`Created issue ${data.idReadable || data.id}\nURL: ${config.baseUrl}/issue/${data.idReadable || data.id}`);
+		},
+	});
+
+	// ── youtrack_update_issue ────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_update_issue",
+		label: "YouTrack Update Issue",
+		description:
+			"Update an existing issue. Can change summary, description, and custom fields (state, priority, type, etc). Use youtrack_get_issue_fields_schema to discover valid field values.",
+		parameters: Type.Object({
+			issue_id: Type.String({ description: "Issue ID (e.g. 'PROJ-123')" }),
+			summary: Type.Optional(Type.String({ description: "New summary" })),
+			description: Type.Optional(Type.String({ description: "New description" })),
+			custom_fields: Type.Optional(Type.Array(
+				Type.Object({
+					name: Type.String({ description: "Custom field name" }),
+					value: Type.Unknown({ description: "New value" }),
+					$type: Type.Optional(Type.String({ description: "Field type" })),
+				}),
+			)),
+		}),
+		promptSnippet: "Update a YouTrack issue",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const body: Record<string, unknown> = {};
+			if (params.summary) body.summary = params.summary;
+			if (params.description !== undefined) body.description = params.description;
+			if (params.custom_fields) body.customFields = params.custom_fields;
+			const res = await ytFetch(config, "POST", `/api/issues/${encodeURIComponent(params.issue_id)}?fields=idReadable,id`, body);
+			if (!res.ok) return err(`Failed to update issue (${res.status}): ${res.text}`);
+			return ok(`Updated issue ${params.issue_id}`);
+		},
+	});
+
+	// ── youtrack_change_assignee ─────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_change_assignee",
+		label: "YouTrack Change Assignee",
+		description:
+			"Change the assignee of an issue. Provide the issue ID and the new assignee's login username.",
+		parameters: Type.Object({
+			issue_id: Type.String({ description: "Issue ID (e.g. 'PROJ-123')" }),
+			assignee: Type.String({ description: "Username (login) of the new assignee" }),
+		}),
+		promptSnippet: "Change YouTrack issue assignee",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const body = {
+				customFields: [{
+					name: "Assignee",
+					$type: "SingleUserIssueCustomField",
+					value: { login: params.assignee },
+				}],
+			};
+			const res = await ytFetch(config, "POST", `/api/issues/${encodeURIComponent(params.issue_id)}?fields=idReadable`, body);
+			if (!res.ok) return err(`Failed to change assignee (${res.status}): ${res.text}`);
+			return ok(`Assigned ${params.issue_id} to @${params.assignee}`);
+		},
+	});
+
+	// ── youtrack_add_comment ─────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_add_comment",
+		label: "YouTrack Add Comment",
+		description:
+			"Add a comment to an issue. Supports Markdown formatting.",
+		parameters: Type.Object({
+			issue_id: Type.String({ description: "Issue ID (e.g. 'PROJ-123')" }),
+			text: Type.String({ description: "Comment text (supports Markdown)" }),
+		}),
+		promptSnippet: "Add a comment to a YouTrack issue",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const res = await ytFetch(config, "POST", `/api/issues/${encodeURIComponent(params.issue_id)}/comments?fields=id,created`, { text: params.text });
+			if (!res.ok) return err(`Failed to add comment (${res.status}): ${res.text}`);
+			return ok(`Comment added to ${params.issue_id}`);
+		},
+	});
+
+	// ── youtrack_get_comments ────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_get_comments",
+		label: "YouTrack Get Comments",
+		description:
+			"Get all comments for an issue, including author, timestamp, and text.",
+		parameters: Type.Object({
+			issue_id: Type.String({ description: "Issue ID (e.g. 'PROJ-123')" }),
+			limit: Type.Optional(Type.Integer({ description: "Max comments. Default 25." })),
+			offset: Type.Optional(Type.Integer({ description: "Skip N comments for pagination." })),
+		}),
+		promptSnippet: "Get comments for a YouTrack issue",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const top = Math.min(params.limit ?? 25, 100);
+			const skip = params.offset ?? 0;
+			const res = await ytFetch(config, "GET", `/api/issues/${encodeURIComponent(params.issue_id)}/comments?fields=id,text,created,author(login,fullName)&$top=${top}&$skip=${skip}`);
+			if (!res.ok) return err(`Failed to get comments (${res.status}): ${res.text}`);
+			const comments = res.data as Array<{ id?: string; text?: string; created?: number; author?: { login?: string; fullName?: string } }>;
+			if (comments.length === 0) return ok("No comments on this issue.");
+			const lines: string[] = [`${comments.length} comment(s):\n`];
+			for (const c of comments) {
+				const author = c.author?.fullName || c.author?.login || "?";
+				lines.push(`[${formatTimestamp(c.created)}] ${author}:`);
+				lines.push(c.text || "(empty)");
+				lines.push("");
+			}
+			return ok(lines.join("\n"));
+		},
+	});
+
+	// ── youtrack_manage_tags ─────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_manage_tags",
+		label: "YouTrack Manage Tags",
+		description:
+			"Add or remove a tag from an issue. If adding by name, the first matching tag is used.",
+		parameters: Type.Object({
+			issue_id: Type.String({ description: "Issue ID (e.g. 'PROJ-123')" }),
+			tag: Type.String({ description: "Tag name or ID" }),
+			action: Type.Union([Type.Literal("add"), Type.Literal("remove")], { description: "'add' or 'remove'" }),
+		}),
+		promptSnippet: "Add or remove a tag on a YouTrack issue",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			if (params.action === "add") {
+				const res = await ytFetch(config, "POST", `/api/issues/${encodeURIComponent(params.issue_id)}/tags?fields=id,name`, { name: params.tag });
+				if (!res.ok) return err(`Failed to add tag (${res.status}): ${res.text}`);
+				return ok(`Added tag "${params.tag}" to ${params.issue_id}`);
+			}
+			// Remove: first find the tag ID
+			const tagsRes = await ytFetch(config, "GET", `/api/issues/${encodeURIComponent(params.issue_id)}?fields=tags(id,name)`);
+			if (!tagsRes.ok) return err(`Failed to get tags (${tagsRes.status}): ${tagsRes.text}`);
+			const issue = tagsRes.data as { tags?: Array<{ id: string; name: string }> };
+			const tag = issue.tags?.find((t) => t.name.toLowerCase() === params.tag.toLowerCase() || t.id === params.tag);
+			if (!tag) return err(`Tag "${params.tag}" not found on ${params.issue_id}`);
+			const res = await ytFetch(config, "DELETE", `/api/issues/${encodeURIComponent(params.issue_id)}/tags/${tag.id}`);
+			if (!res.ok) return err(`Failed to remove tag (${res.status}): ${res.text}`);
+			return ok(`Removed tag "${params.tag}" from ${params.issue_id}`);
+		},
+	});
+
+	// ── youtrack_link_issues ─────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_link_issues",
+		label: "YouTrack Link Issues",
+		description:
+			"Link two issues with a specified link type (e.g. 'relates to', 'depends on', 'parent for', 'subtask of', 'duplicates').",
+		parameters: Type.Object({
+			issue_id: Type.String({ description: "Source issue ID (e.g. 'PROJ-123')" }),
+			target_issue_id: Type.String({ description: "Target issue ID to link to" }),
+			link_type: Type.String({ description: "Link type name (e.g. 'relates to', 'depends on', 'parent for')" }),
+		}),
+		promptSnippet: "Link two YouTrack issues",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const body = {
+				issues: [{ idReadable: params.target_issue_id }],
+				linkType: { name: params.link_type },
+			};
+			const res = await ytFetch(config, "POST", `/api/issues/${encodeURIComponent(params.issue_id)}/links?fields=id`, body);
+			if (!res.ok) return err(`Failed to link issues (${res.status}): ${res.text}`);
+			return ok(`Linked ${params.issue_id} → ${params.target_issue_id} (${params.link_type})`);
+		},
+	});
+
+	// ── youtrack_find_projects ───────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_find_projects",
+		label: "YouTrack Find Projects",
+		description:
+			"Search for projects by name. Returns project ID, name, and short name.",
+		parameters: Type.Object({
+			query: Type.Optional(Type.String({ description: "Project name substring to search for (case-insensitive). Returns all projects if omitted." })),
+			limit: Type.Optional(Type.Integer({ description: "Max results. Default 25." })),
+		}),
+		promptSnippet: "Find YouTrack projects",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const top = Math.min(params.limit ?? 25, 100);
+			let path = `/api/admin/projects?fields=id,name,shortName&$top=${top}`;
+			if (params.query) path += `&query=${encodeURIComponent(params.query)}`;
+			const res = await ytFetch(config, "GET", path);
+			if (!res.ok) return err(`Failed to find projects (${res.status}): ${res.text}`);
+			const projects = res.data as Array<{ id: string; name: string; shortName: string }>;
+			if (projects.length === 0) return ok("No projects found.");
+			const lines = projects.map((p) => `${p.shortName} (${p.id}): ${p.name}`);
+			return ok(`${projects.length} project(s):\n${lines.join("\n")}`);
+		},
+	});
+
+	// ── youtrack_get_project ─────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_get_project",
+		label: "YouTrack Get Project",
+		description:
+			"Get full details for a project including name, description, leader, and creation date.",
+		parameters: Type.Object({
+			project_id: Type.String({ description: "Project ID (database ID like '0-3' or short name like 'PROJ')" }),
+		}),
+		promptSnippet: "Get YouTrack project details",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const res = await ytFetch(config, "GET", `/api/admin/projects/${encodeURIComponent(params.project_id)}?fields=id,name,shortName,description,leader(login,fullName),createdBy(login,fullName),archived,fromEmail,replyToEmail`);
+			if (!res.ok) return err(`Failed to get project (${res.status}): ${res.text}`);
+			const p = res.data as Record<string, unknown>;
+			const lines: string[] = [];
+			lines.push(`${p.shortName} (${p.id}): ${p.name}`);
+			if (p.description) lines.push(`Description: ${p.description}`);
+			if (p.leader) {
+				const l = p.leader as { login?: string; fullName?: string };
+				lines.push(`Leader: ${l.fullName || l.login || "?"}`);
+			}
+			if (p.archived) lines.push("Status: Archived");
+			return ok(lines.join("\n"));
+		},
+	});
+
+	// ── youtrack_get_issue_fields_schema ─────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_get_issue_fields_schema",
+		label: "YouTrack Fields Schema",
+		description:
+			"Get the custom field schema for a project — field names, types, required status, and possible values. Essential before creating or updating issues.",
+		parameters: Type.Object({
+			project_id: Type.String({ description: "Project ID (database ID like '0-3' or short name like 'PROJ')" }),
+		}),
+		promptSnippet: "Get YouTrack custom field schema for a project",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const res = await ytFetch(config, "GET", `/api/admin/projects/${encodeURIComponent(params.project_id)}/customFields?fields=id,field(name,fieldType(id)),canBeEmpty,emptyFieldText,bundle(id,values(name,login,fullName))`);
+			if (!res.ok) return err(`Failed to get schema (${res.status}): ${res.text}`);
+			const fields = res.data as Array<{
+				id: string;
+				field: { name: string; fieldType?: { id?: string } };
+				canBeEmpty?: boolean;
+				emptyFieldText?: string;
+				bundle?: { values?: Array<{ name?: string; login?: string; fullName?: string }> };
+			}>;
+			if (fields.length === 0) return ok("No custom fields configured for this project.");
+			const lines: string[] = [`${fields.length} custom field(s):\n`];
+			for (const f of fields) {
+				const required = f.canBeEmpty === false ? " (required)" : "";
+				const type = f.field.fieldType?.id || "unknown";
+				lines.push(`${f.field.name} [${type}]${required}`);
+				if (f.bundle?.values && f.bundle.values.length > 0) {
+					const vals = f.bundle.values.map((v) => v.name || v.fullName || v.login || "?");
+					lines.push(`  Values: ${vals.join(", ")}`);
+				}
+			}
+			return ok(lines.join("\n"));
+		},
+	});
+
+	// ── youtrack_find_user ───────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_find_user",
+		label: "YouTrack Find User",
+		description:
+			"Find a user by username, full name, or email. Returns profile data.",
+		parameters: Type.Object({
+			query: Type.String({ description: "Username, full name, or email to search for" }),
+		}),
+		promptSnippet: "Find a YouTrack user",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const res = await ytFetch(config, "GET", `/api/users?fields=id,login,fullName,email,banned&query=${encodeURIComponent(params.query)}&$top=10`);
+			if (!res.ok) return err(`Failed to find user (${res.status}): ${res.text}`);
+			const users = res.data as Array<{ id: string; login: string; fullName?: string; email?: string; banned?: boolean }>;
+			if (users.length === 0) return ok("No users found.");
+			const lines = users.map((u) => {
+				const parts = [`@${u.login}`];
+				if (u.fullName) parts.push(`(${u.fullName})`);
+				if (u.email) parts.push(`<${u.email}>`);
+				if (u.banned) parts.push("[banned]");
+				return parts.join(" ");
+			});
+			return ok(`${users.length} user(s):\n${lines.join("\n")}`);
+		},
+	});
+
+	// ── youtrack_get_current_user ────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_get_current_user",
+		label: "YouTrack Current User",
+		description:
+			"Get details about the currently authenticated user — username, email, full name.",
+		parameters: Type.Object({}),
+		promptSnippet: "Get current YouTrack user info",
+		async execute() {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const res = await ytFetch(config, "GET", "/api/users/me?fields=id,login,fullName,email,avatarUrl");
+			if (!res.ok) return err(`Failed to get user (${res.status}): ${res.text}`);
+			const u = res.data as { login?: string; fullName?: string; email?: string };
+			const lines: string[] = [];
+			if (u.fullName) lines.push(`Name: ${u.fullName}`);
+			if (u.login) lines.push(`Login: @${u.login}`);
+			if (u.email) lines.push(`Email: ${u.email}`);
+			return ok(lines.join("\n"));
+		},
+	});
+
+	// ── youtrack_search_articles ─────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_search_articles",
+		label: "YouTrack Search Articles",
+		description:
+			"Search for knowledge base articles using YouTrack query language.",
+		parameters: Type.Object({
+			query: Type.String({ description: "Search query for articles" }),
+			limit: Type.Optional(Type.Integer({ description: "Max results. Default 25." })),
+			offset: Type.Optional(Type.Integer({ description: "Skip N results." })),
+		}),
+		promptSnippet: "Search YouTrack knowledge base articles",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const top = Math.min(params.limit ?? 25, 100);
+			const skip = params.offset ?? 0;
+			const q = encodeURIComponent(params.query);
+			const res = await ytFetch(config, "GET", `/api/articles?fields=id,idReadable,summary,project(name)&query=${q}&$top=${top}&$skip=${skip}`);
+			if (!res.ok) return err(`Failed to search articles (${res.status}): ${res.text}`);
+			const articles = res.data as Array<{ id: string; idReadable?: string; summary?: string; project?: { name?: string } }>;
+			if (articles.length === 0) return ok("No articles found.");
+			const lines = articles.map((a) => `${a.idReadable || a.id}: ${a.summary || "(no title)"}${a.project?.name ? ` [${a.project.name}]` : ""}`);
+			return ok(`${articles.length} article(s):\n${lines.join("\n")}`);
+		},
+	});
+
+	// ── youtrack_get_article ─────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_get_article",
+		label: "YouTrack Get Article",
+		description:
+			"Get full content of a knowledge base article including title, content, and sub-articles.",
+		parameters: Type.Object({
+			article_id: Type.String({ description: "Article ID (e.g. 'PROJ-A-1')" }),
+		}),
+		promptSnippet: "Get a YouTrack knowledge base article",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const res = await ytFetch(config, "GET", `/api/articles/${encodeURIComponent(params.article_id)}?fields=id,idReadable,summary,content,project(name),reporter(login,fullName),created,updated,childArticles(id,idReadable,summary)`);
+			if (!res.ok) return err(`Failed to get article (${res.status}): ${res.text}`);
+			const a = res.data as Record<string, unknown>;
+			const lines: string[] = [];
+			lines.push(`# ${a.summary || "(no title)"}`);
+			if (a.project) lines.push(`Project: ${(a.project as { name?: string }).name || "?"}`);
+			if (a.reporter) {
+				const r = a.reporter as { login?: string; fullName?: string };
+				lines.push(`Author: ${r.fullName || r.login || "?"}`);
+			}
+			if (a.created) lines.push(`Created: ${formatTimestamp(a.created as number)}`);
+			if (a.updated) lines.push(`Updated: ${formatTimestamp(a.updated as number)}`);
+			lines.push("");
+			if (a.content) lines.push(String(a.content));
+			const children = a.childArticles as Array<{ idReadable?: string; summary?: string }> | undefined;
+			if (children && children.length > 0) {
+				lines.push("\nSub-articles:");
+				for (const c of children) {
+					lines.push(`  ${c.idReadable}: ${c.summary || "(no title)"}`);
+				}
+			}
+			return ok(lines.join("\n"));
+		},
+	});
+
+	// ── youtrack_create_article ──────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_create_article",
+		label: "YouTrack Create Article",
+		description:
+			"Create a new knowledge base article in a project.",
+		parameters: Type.Object({
+			project_id: Type.String({ description: "Project ID" }),
+			summary: Type.String({ description: "Article title" }),
+			content: Type.String({ description: "Article content (supports Markdown)" }),
+			parent_article_id: Type.Optional(Type.String({ description: "Parent article ID to nest under" })),
+		}),
+		promptSnippet: "Create a YouTrack knowledge base article",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const body: Record<string, unknown> = {
+				summary: params.summary,
+				content: params.content,
+				project: { id: params.project_id },
+			};
+			if (params.parent_article_id) body.parentArticle = { id: params.parent_article_id };
+			const res = await ytFetch(config, "POST", "/api/articles?fields=id,idReadable", body);
+			if (!res.ok) return err(`Failed to create article (${res.status}): ${res.text}`);
+			const data = res.data as { idReadable?: string; id?: string };
+			return ok(`Created article ${data.idReadable || data.id}\nURL: ${config.baseUrl}/articles/${data.idReadable || data.id}`);
+		},
+	});
+
+	// ── youtrack_log_work ────────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "youtrack_log_work",
+		label: "YouTrack Log Work",
+		description:
+			"Log time spent on an issue. Specify duration in minutes.",
+		parameters: Type.Object({
+			issue_id: Type.String({ description: "Issue ID (e.g. 'PROJ-123')" }),
+			minutes: Type.Integer({ description: "Duration in minutes" }),
+			description: Type.Optional(Type.String({ description: "Work item description" })),
+			date: Type.Optional(Type.String({ description: "Date (ISO 8601, e.g. '2026-05-27'). Defaults to today." })),
+			work_type: Type.Optional(Type.String({ description: "Work type name (e.g. 'Development', 'Testing'). Use youtrack_get_project to see available work types." })),
+		}),
+		promptSnippet: "Log work time on a YouTrack issue",
+		async execute(_id, params) {
+			const config = getConfig(getCwd());
+			if (!config) return noConfig();
+			const body: Record<string, unknown> = {
+				duration: { minutes: params.minutes },
+			};
+			if (params.description) body.text = params.description;
+			if (params.date) body.date = new Date(params.date).getTime();
+			if (params.work_type) body.type = { name: params.work_type };
+			const res = await ytFetch(config, "POST", `/api/issues/${encodeURIComponent(params.issue_id)}/timeTracking/workItems?fields=id`, body);
+			if (!res.ok) return err(`Failed to log work (${res.status}): ${res.text}`);
+			return ok(`Logged ${params.minutes} minutes on ${params.issue_id}`);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@elyracode/youtrack",
+  "version": "0.8.1",
+  "description": "YouTrack integration for Elyra -- search issues, manage assignments, comments, projects, and more",
+  "type": "module",
+  "keywords": [
+    "elyra-package",
+    "youtrack",
+    "jetbrains",
+    "issue-tracker",
+    "project-management"
+  ],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/youtrack"
+  },
+  "elyra": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}

package/skills/elyra-youtrack/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: elyra-youtrack
+description: YouTrack issue tracker integration. Use when the user asks about issues, bugs, tasks, sprints, projects, time tracking, or anything related to their YouTrack instance.
+---
+
+# YouTrack Integration
+
+## When to Use
+
+Use YouTrack tools when:
+- The user asks about issues, bugs, tasks, or tickets
+- The user wants to search, create, update, or comment on issues
+- The user asks about project status, sprints, or backlogs
+- The user needs to look up knowledge base articles
+- The user wants to log or review time spent on issues
+- The user references YouTrack issue IDs (e.g. `PROJ-123`)
+
+## Available Tools
+
+| Tool | Use when |
+|------|----------|
+| `youtrack_search_issues` | Finding issues by query, status, assignee, project, etc. |
+| `youtrack_get_issue` | Getting full details of a specific issue by ID |
+| `youtrack_create_issue` | Creating a new issue (always get project schema first) |
+| `youtrack_update_issue` | Changing fields like state, assignee, priority, summary |
+| `youtrack_delete_issue` | Removing an issue permanently |
+| `youtrack_list_comments` | Reading discussion on an issue |
+| `youtrack_add_comment` | Posting a comment on an issue |
+| `youtrack_list_tags` | Browsing available tags for filtering or applying |
+| `youtrack_apply_tag` | Tagging or untagging an issue |
+| `youtrack_list_links` | Viewing issue relationships (parent, subtask, duplicate, related) |
+| `youtrack_add_link` | Linking two issues together |
+| `youtrack_list_projects` | Listing all accessible projects |
+| `youtrack_get_project` | Getting project details and custom field schema |
+| `youtrack_list_users` | Finding users for assignment or mentions |
+| `youtrack_get_current_user` | Getting the authenticated user's profile |
+| `youtrack_search_articles` | Searching the knowledge base |
+| `youtrack_get_article` | Reading a specific knowledge base article |
+| `youtrack_add_work_item` | Logging time spent on an issue |
+
+## YouTrack Query Syntax
+
+Use these query terms with `youtrack_search_issues`:
+
+| Query | Meaning |
+|-------|---------|
+| `for: me` | Issues assigned to the current user |
+| `by: me` | Issues reported by the current user |
+| `#Unresolved` | Issues that are not yet resolved |
+| `#Resolved` | Issues that have been resolved |
+| `project: PROJ` | Issues in a specific project |
+| `Priority: Critical` | Issues with a specific priority |
+| `Type: Bug` | Issues of a specific type |
+| `created: today` | Issues created today |
+| `created: this week` | Issues created this week |
+| `updated: yesterday .. today` | Issues updated in a date range |
+| `sort by: created desc` | Sort by creation date, newest first |
+| `sort by: updated asc` | Sort by update date, oldest first |
+| `sort by: Priority desc` | Sort by priority, highest first |
+
+Combine terms freely: `project: PROJ #Unresolved for: me sort by: Priority desc`
+
+## Issue Creation Workflow
+
+When creating issues, always follow this sequence:
+
+1. **Get the project schema first** -- call `youtrack_get_project` to retrieve the project's custom fields, required fields, and allowed values.
+2. **Create the issue** -- call `youtrack_create_issue` with the correct field values based on the schema.
+
+This prevents validation errors from incorrect or missing custom field values.
+
+## Common Query Patterns
+
+| Goal | Query |
+|------|-------|
+| My open issues | `for: me #Unresolved` |
+| My open bugs | `for: me #Unresolved Type: Bug` |
+| Unresolved critical issues in a project | `project: PROJ #Unresolved Priority: Critical` |
+| Issues I reported that are still open | `by: me #Unresolved` |
+| Recently updated issues | `updated: today sort by: updated desc` |
+| Issues created this week | `created: this week sort by: created desc` |
+| All issues for a specific tag | `tag: backend` |
+| Unresolved issues with no assignee | `#Unresolved has: -Assignee` |
+
+## Rules
+
+- Always call `youtrack_get_project` before `youtrack_create_issue` to learn the field schema
+- Use `youtrack_search_issues` to verify an issue exists before attempting updates
+- When the user says "my issues", use `for: me` (assigned) unless they clarify they mean reported (`by: me`)
+- Prefer searching by issue ID when the user provides one (e.g. `PROJ-123`) rather than a text search
+- Add `#Unresolved` to queries unless the user explicitly asks for resolved or all issues