@danypops/tickets 0.1.0

package/src/adapters/gitlab.ts

@@ -0,0 +1,237 @@
+/**
+ * GitLab adapter — driven implementation of IssueRepository/CommentCapable against
+ * the GitLab REST API v4 (docs: https://docs.gitlab.com/api/issues/).
+ * Self-hosted base URLs are validated to reject SSRF-prone targets (private/loopback
+ * IPs, non-HTTPS non-localhost) before any request is made.
+ */
+import { isIP } from "node:net";
+import type { Comment, CreateInput, Issue, ListFilter, Status, UpdateInput } from "../domain/issue.js";
+import { parsePriority } from "../domain/issue.js";
+import { AuthRequiredError, InvalidUrlError } from "./errors.js";
+import { type FetchLike, HttpClient } from "./http.js";
+
+export interface GitLabOptions {
+  projectId: string;
+  token?: string;
+  /**
+   * "private" (default): PRIVATE-TOKEN header, for personal/project access tokens.
+   * "oauth": Authorization: Bearer header, for OAuth 2.0 access tokens (see
+   * auth/gitlab-oauth.ts) — GitLab documents these as distinct auth schemes.
+   */
+  tokenType?: "private" | "oauth";
+  baseUrl?: string;
+  fetchImpl?: FetchLike;
+}
+
+interface GlUser {
+  username: string;
+  name: string;
+}
+interface GlIssue {
+  id: number;
+  iid: number;
+  title: string;
+  description: string | null;
+  state: string;
+  web_url: string;
+  author: GlUser | null;
+  assignee: GlUser | null;
+  labels: string[];
+  created_at: string;
+  updated_at: string;
+}
+interface GlNote {
+  id: number;
+  body: string;
+  created_at: string;
+  updated_at: string;
+  author: GlUser | null;
+}
+
+const DEFAULT_URL = "https://gitlab.com";
+
+export class GitLabRepository {
+  readonly name: string;
+  private readonly http: HttpClient;
+  private readonly projectId: string;
+  private readonly readOnly: boolean;
+
+  constructor(name: string, opts: GitLabOptions) {
+    if (!opts.projectId) throw new Error("gitlab: projectId is required");
+    const baseUrl = opts.baseUrl?.trim() || DEFAULT_URL;
+    validateUrl(baseUrl);
+    this.name = name;
+    this.projectId = encodeURIComponent(opts.projectId);
+    this.readOnly = !opts.token;
+    this.http = new HttpClient({
+      baseUrl,
+      backend: "gitlab",
+      fetchImpl: opts.fetchImpl,
+      headers: opts.token
+        ? opts.tokenType === "oauth"
+          ? { Authorization: `Bearer ${opts.token}` }
+          : { "PRIVATE-TOKEN": opts.token }
+        : {},
+    });
+  }
+
+  private requireAuth(): void {
+    if (this.readOnly) throw new AuthRequiredError("gitlab", "GITLAB_TOKEN");
+  }
+
+  async list(filter: ListFilter): Promise<Issue[]> {
+    const limit = filter.limit && filter.limit > 0 ? filter.limit : 50;
+    const params = new URLSearchParams({ per_page: String(limit) });
+    if (filter.status) params.set("state", mapStatusToGitLab(filter.status));
+    if (filter.assignee) params.set("assignee_username", filter.assignee);
+    if (filter.labels?.length) params.set("labels", filter.labels.join(","));
+
+    const raw = (await this.http.get<GlIssue[]>(`/api/v4/projects/${this.projectId}/issues?${params}`)) ?? [];
+    return raw.map(toDomain);
+  }
+
+  async get(key: string): Promise<Issue> {
+    const iid = parseIid(key);
+    const raw = await this.http.get<GlIssue>(`/api/v4/projects/${this.projectId}/issues/${iid}`);
+    if (!raw) throw new Error(`gitlab: empty response for #${iid}`);
+    return toDomain(raw);
+  }
+
+  async create(input: CreateInput): Promise<Issue> {
+    this.requireAuth();
+    const body: Record<string, unknown> = { title: input.title, description: input.description ?? "" };
+    if (input.labels?.length) body.labels = input.labels.join(",");
+    const raw = await this.http.post<GlIssue>(`/api/v4/projects/${this.projectId}/issues`, body);
+    if (!raw) throw new Error("gitlab: create returned no body");
+    return toDomain(raw);
+  }
+
+  async update(key: string, input: UpdateInput): Promise<Issue> {
+    this.requireAuth();
+    const iid = parseIid(key);
+    const body: Record<string, unknown> = {};
+    if (input.title !== undefined) body.title = input.title;
+    if (input.description !== undefined) body.description = input.description;
+    if (input.status !== undefined) body.state_event = mapStatusEventToGitLab(input.status);
+    if (input.labels !== undefined) body.labels = input.labels.join(",");
+    const raw = await this.http.put<GlIssue>(`/api/v4/projects/${this.projectId}/issues/${iid}`, body);
+    if (!raw) throw new Error("gitlab: update returned no body");
+    return toDomain(raw);
+  }
+
+  async search(query: string, limit = 50): Promise<Issue[]> {
+    const params = new URLSearchParams({ search: query, per_page: String(limit) });
+    const raw = (await this.http.get<GlIssue[]>(`/api/v4/projects/${this.projectId}/issues?${params}`)) ?? [];
+    return raw.map(toDomain);
+  }
+
+  // GitLab has no native sub-issue relationship exposed via the basic Issues API tier.
+  async listChildren(_key: string): Promise<Issue[]> {
+    return [];
+  }
+
+  async listComments(key: string): Promise<Comment[]> {
+    const iid = parseIid(key);
+    const raw = (await this.http.get<GlNote[]>(`/api/v4/projects/${this.projectId}/issues/${iid}/notes`)) ?? [];
+    return raw.map(noteToDomain);
+  }
+
+  async addComment(key: string, body: string): Promise<Comment> {
+    this.requireAuth();
+    const iid = parseIid(key);
+    const raw = await this.http.post<GlNote>(`/api/v4/projects/${this.projectId}/issues/${iid}/notes`, { body });
+    if (!raw) throw new Error("gitlab: add comment returned no body");
+    return noteToDomain(raw);
+  }
+}
+
+function parseIid(key: string): string {
+  return key.replace(/^#/, "");
+}
+
+function mapStatusToGitLab(status: Status): "opened" | "closed" {
+  return status === "done" || status === "canceled" ? "closed" : "opened";
+}
+
+function mapStatusEventToGitLab(status: Status): "close" | "reopen" {
+  return status === "done" || status === "canceled" ? "close" : "reopen";
+}
+
+function mapStatusFromGitLab(state: string): Status {
+  return state.toLowerCase() === "closed" ? "done" : "todo";
+}
+
+function priorityFromLabels(labels: string[]): ReturnType<typeof parsePriority> {
+  for (const l of labels) {
+    const lower = l.toLowerCase();
+    if (lower.includes("urgent") || lower.includes("critical")) return "urgent";
+    if (lower.includes("high")) return "high";
+    if (lower.includes("medium")) return "medium";
+    if (lower.includes("low")) return "low";
+  }
+  return "none";
+}
+
+function toDomain(gl: GlIssue): Issue {
+  return {
+    ref: `gitlab:#${gl.iid}`,
+    id: String(gl.iid),
+    key: `#${gl.iid}`,
+    title: gl.title,
+    description: gl.description ?? undefined,
+    status: mapStatusFromGitLab(gl.state),
+    rawStatus: gl.state,
+    priority: priorityFromLabels(gl.labels ?? []),
+    labels: gl.labels?.length ? gl.labels : undefined,
+    assignee: gl.assignee?.username,
+    reporter: gl.author?.username,
+    url: gl.web_url,
+    createdAt: gl.created_at,
+    updatedAt: gl.updated_at,
+  };
+}
+
+function noteToDomain(n: GlNote): Comment {
+  return {
+    id: String(n.id),
+    body: n.body,
+    author: n.author?.username,
+    createdAt: n.created_at,
+    updatedAt: n.updated_at,
+  };
+}
+
+/**
+ * SSRF guard for self-hosted GitLab base URLs: require https (or http only for
+ * localhost), and reject requests aimed at loopback/link-local/private IP ranges.
+ */
+export function validateUrl(rawUrl: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new InvalidUrlError(`gitlab: invalid URL: ${rawUrl}`);
+  }
+
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new InvalidUrlError(`gitlab: scheme must be http(s) (got ${parsed.protocol})`);
+  }
+  if (parsed.protocol === "http:" && parsed.hostname !== "localhost") {
+    throw new InvalidUrlError(
+      `gitlab: http:// only allowed for localhost (got ${parsed.hostname}); use https:// for remote instances`,
+    );
+  }
+  if (isIP(parsed.hostname) && isPrivateIp(parsed.hostname)) {
+    throw new InvalidUrlError("gitlab: private IP addresses are not allowed (blocks SSRF)");
+  }
+}
+
+function isPrivateIp(ip: string): boolean {
+  if (ip === "127.0.0.1" || ip === "::1") return true;
+  if (/^169\.254\./.test(ip) || ip.startsWith("fe80:")) return true;
+  if (/^10\./.test(ip)) return true;
+  if (/^192\.168\./.test(ip)) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(ip)) return true;
+  if (/^f[cd][0-9a-f]{2}:/i.test(ip)) return true;
+  return false;
+}

package/src/adapters/http.ts

@@ -0,0 +1,86 @@
+import { ApiError, IssueNotFoundError } from "./errors.js";
+
+export type FetchLike = typeof fetch;
+
+export interface HttpClientOptions {
+  baseUrl: string;
+  backend: string;
+  headers?: Record<string, string>;
+  fetchImpl?: FetchLike;
+  timeoutMs?: number;
+}
+
+/**
+ * Thin authenticated JSON HTTP client shared by all adapters. Each adapter owns its
+ * own auth header construction (Bearer, Basic, PRIVATE-TOKEN, ...) and passes it in
+ * via `headers`. Accepts an injectable `fetchImpl` so adapters are testable without
+ * a network — see test/adapters/*.test.ts.
+ */
+export class HttpClient {
+  private readonly baseUrl: string;
+  private readonly backend: string;
+  private readonly headers: Record<string, string>;
+  private readonly fetchImpl: FetchLike;
+  private readonly timeoutMs: number;
+
+  constructor(opts: HttpClientOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.backend = opts.backend;
+    this.headers = opts.headers ?? {};
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.timeoutMs = opts.timeoutMs ?? 30_000;
+  }
+
+  async request<T>(method: string, path: string, body?: unknown): Promise<T | undefined> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(this.baseUrl + path, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          ...this.headers,
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (res.status === 404) {
+        throw new IssueNotFoundError(this.backend, path);
+      }
+      if (res.status === 204) {
+        return undefined;
+      }
+
+      const text = await res.text();
+      if (!res.ok) {
+        throw new ApiError(this.backend, method, path, res.status, redact(text));
+      }
+      if (text.length === 0) return undefined;
+      return JSON.parse(text) as T;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  get<T>(path: string): Promise<T | undefined> {
+    return this.request<T>("GET", path);
+  }
+  post<T>(path: string, body?: unknown): Promise<T | undefined> {
+    return this.request<T>("POST", path, body);
+  }
+  put<T>(path: string, body?: unknown): Promise<T | undefined> {
+    return this.request<T>("PUT", path, body);
+  }
+  patch<T>(path: string, body?: unknown): Promise<T | undefined> {
+    return this.request<T>("PATCH", path, body);
+  }
+}
+
+/** Strips anything that looks like a bearer/basic credential from error bodies before logging. */
+function redact(text: string): string {
+  return text
+    .replace(/"(token|password|secret|api_key|authorization)"\s*:\s*"[^"]*"/gi, '"$1":"[redacted]"')
+    .slice(0, 2000);
+}

package/src/adapters/jira.ts

@@ -0,0 +1,311 @@
+/**
+ * Jira adapter — driven implementation of IssueRepository/CommentCapable against the
+ * Jira Cloud/Server REST API v2 (docs: https://developer.atlassian.com/cloud/jira/platform/rest/v2/).
+ * Status changes go through Jira's workflow transitions, not a direct field PUT —
+ * Jira statuses are workflow-owned, so we resolve the transition whose name matches
+ * the mapped target status and post to it.
+ */
+import type { Comment, CreateInput, Issue, ListFilter, Status, UpdateInput } from "../domain/issue.js";
+import { parsePriority } from "../domain/issue.js";
+import { type FetchLike, HttpClient } from "./http.js";
+
+/**
+ * Basic-auth mode (email + API token) hits the tenant's own *.atlassian.net
+ * domain directly. OAuth 2.0 (3LO) mode (accessToken + cloudId, see
+ * auth/jira-oauth.ts) instead goes through api.atlassian.com/ex/jira/{cloudId}
+ * with a Bearer token — Atlassian does not accept 3LO tokens against the
+ * tenant domain directly. Exactly one of the two auth modes must be given.
+ */
+export type JiraOptions = JiraBasicAuthOptions | JiraOAuthOptions;
+
+export interface JiraBasicAuthOptions {
+  baseUrl: string;
+  email: string;
+  token: string;
+  project?: string;
+  fetchImpl?: FetchLike;
+}
+
+export interface JiraOAuthOptions {
+  accessToken: string;
+  cloudId: string;
+  project?: string;
+  fetchImpl?: FetchLike;
+}
+
+function isOAuthOptions(opts: JiraOptions): opts is JiraOAuthOptions {
+  return "accessToken" in opts;
+}
+
+interface JiraIssueFields {
+  summary: string;
+  description?: string | null;
+  status: { name: string; statusCategory?: { key: string } };
+  priority?: { name: string } | null;
+  assignee?: { displayName: string } | null;
+  reporter?: { displayName: string } | null;
+  labels?: string[];
+  project?: { key: string };
+  issuetype?: { name: string };
+  resolution?: { name: string } | null;
+  parent?: { key: string; fields?: { summary: string; status?: { name: string } } };
+  created?: string;
+  updated?: string;
+}
+interface JiraIssue {
+  id: string;
+  key: string;
+  self: string;
+  fields: JiraIssueFields;
+}
+interface JiraTransition {
+  id: string;
+  name: string;
+}
+interface JiraComment {
+  id: string;
+  body: string;
+  created: string;
+  updated: string;
+  author?: { displayName: string };
+}
+
+export class JiraRepository {
+  readonly name: string;
+  private readonly http: HttpClient;
+  private readonly project?: string;
+
+  constructor(name: string, opts: JiraOptions) {
+    this.name = name;
+    this.project = opts.project;
+
+    if (isOAuthOptions(opts)) {
+      if (!opts.accessToken || !opts.cloudId) throw new Error("jira: accessToken and cloudId are required for OAuth mode");
+      this.http = new HttpClient({
+        baseUrl: `https://api.atlassian.com/ex/jira/${opts.cloudId}`,
+        backend: "jira",
+        fetchImpl: opts.fetchImpl,
+        headers: { Authorization: `Bearer ${opts.accessToken}` },
+      });
+      return;
+    }
+
+    if (!opts.baseUrl) throw new Error("jira: baseUrl is required");
+    if (!opts.email || !opts.token) throw new Error("jira: email and token are required");
+    const basic = Buffer.from(`${opts.email}:${opts.token}`).toString("base64");
+    this.http = new HttpClient({
+      baseUrl: opts.baseUrl,
+      backend: "jira",
+      fetchImpl: opts.fetchImpl,
+      headers: { Authorization: `Basic ${basic}` },
+    });
+  }
+
+  async list(filter: ListFilter): Promise<Issue[]> {
+    const project = filter.project ?? this.project;
+    const clauses: string[] = [];
+    if (project) clauses.push(`project = ${jqlQuote(project)}`);
+    if (filter.status) clauses.push(`status = ${jqlQuote(mapStatusToJira(filter.status))}`);
+    if (filter.assignee) clauses.push(`assignee = ${jqlQuote(filter.assignee)}`);
+    for (const label of filter.labels ?? []) clauses.push(`labels = ${jqlQuote(label)}`);
+    const jql = `${clauses.join(" AND ")} ORDER BY created DESC`.trim();
+    return this.searchJql(jql, filter.limit ?? 50);
+  }
+
+  async get(key: string): Promise<Issue> {
+    const raw = await this.http.get<JiraIssue>(`/rest/api/2/issue/${key}`);
+    if (!raw) throw new Error(`jira: empty response for ${key}`);
+    return toDomain(raw);
+  }
+
+  async create(input: CreateInput): Promise<Issue> {
+    const project = input.project ?? this.project;
+    if (!project) throw new Error("jira: project is required (pass project or set a default)");
+    const fields: Record<string, unknown> = {
+      project: { key: project },
+      summary: input.title,
+      issuetype: { name: input.issueType ?? "Task" },
+    };
+    if (input.description) fields.description = input.description;
+    if (input.labels?.length) fields.labels = input.labels;
+    if (input.parentKey) fields.parent = { key: input.parentKey };
+    if (input.priority && input.priority !== "none") {
+      fields.priority = { name: mapPriorityToJira(input.priority) };
+    }
+    const result = await this.http.post<{ key: string }>("/rest/api/2/issue", { fields });
+    if (!result) throw new Error("jira: create returned no body");
+    return this.get(result.key);
+  }
+
+  async update(key: string, input: UpdateInput): Promise<Issue> {
+    const fields: Record<string, unknown> = {};
+    if (input.title !== undefined) fields.summary = input.title;
+    if (input.description !== undefined) fields.description = input.description;
+    if (input.priority !== undefined) fields.priority = { name: mapPriorityToJira(input.priority) };
+    if (input.labels !== undefined) fields.labels = input.labels;
+    if (Object.keys(fields).length > 0) {
+      await this.http.put(`/rest/api/2/issue/${key}`, { fields });
+    }
+    if (input.status !== undefined) {
+      await this.transitionTo(key, input.status, input.resolution);
+    }
+    return this.get(key);
+  }
+
+  async search(query: string, limit = 50): Promise<Issue[]> {
+    const scope = this.project ? `project = ${jqlQuote(this.project)} AND ` : "";
+    const jql = `${scope}text ~ ${jqlQuote(query)} ORDER BY created DESC`;
+    return this.searchJql(jql, limit);
+  }
+
+  async listChildren(key: string): Promise<Issue[]> {
+    return this.searchJql(`parent = ${key} ORDER BY created ASC`, 50);
+  }
+
+  async listComments(key: string): Promise<Comment[]> {
+    const result = await this.http.get<{ comments: JiraComment[] }>(`/rest/api/2/issue/${key}/comment`);
+    return (result?.comments ?? []).map(commentToDomain);
+  }
+
+  async addComment(key: string, body: string): Promise<Comment> {
+    const raw = await this.http.post<JiraComment>(`/rest/api/2/issue/${key}/comment`, { body });
+    if (!raw) throw new Error("jira: add comment returned no body");
+    return commentToDomain(raw);
+  }
+
+  private async searchJql(jql: string, limit: number): Promise<Issue[]> {
+    const result = await this.http.post<{ issues: JiraIssue[] }>("/rest/api/2/search", {
+      jql,
+      maxResults: limit,
+    });
+    return (result?.issues ?? []).map(toDomain);
+  }
+
+  private async transitionTo(key: string, status: Status, resolution?: string): Promise<void> {
+    const target = mapStatusToJira(status);
+    const result = await this.http.get<{ transitions: JiraTransition[] }>(
+      `/rest/api/2/issue/${key}/transitions`,
+    );
+    const transitions = result?.transitions ?? [];
+    const match = transitions.find((t) => t.name.toLowerCase() === target.toLowerCase());
+    if (!match) {
+      const available = transitions.map((t) => t.name).join(", ");
+      throw new Error(`jira: no transition matching "${target}" (available: ${available})`);
+    }
+    const body: Record<string, unknown> = { transition: { id: match.id } };
+    if (resolution) body.fields = { resolution: { name: resolution } };
+    await this.http.post(`/rest/api/2/issue/${key}/transitions`, body);
+  }
+}
+
+function jqlQuote(value: string): string {
+  return `"${value.replace(/"/g, '\\"')}"`;
+}
+
+function mapStatusToJira(status: Status): string {
+  switch (status) {
+    case "backlog":
+      return "Backlog";
+    case "todo":
+      return "New";
+    case "in_progress":
+      return "In Progress";
+    case "in_review":
+      return "In Review";
+    case "done":
+      return "Done";
+    case "canceled":
+      return "Closed";
+    default:
+      return "New";
+  }
+}
+
+function mapStatusFromJira(categoryKey: string | undefined): Status {
+  switch (categoryKey) {
+    case "new":
+      return "todo";
+    case "indeterminate":
+      return "in_progress";
+    case "done":
+      return "done";
+    default:
+      return "backlog";
+  }
+}
+
+function mapPriorityToJira(p: ReturnType<typeof parsePriority>): string {
+  switch (p) {
+    case "urgent":
+      return "Critical";
+    case "high":
+      return "Major";
+    case "medium":
+      return "Normal";
+    case "low":
+      return "Minor";
+    default:
+      return "Normal";
+  }
+}
+
+function mapPriorityFromJira(name: string | undefined): ReturnType<typeof parsePriority> {
+  if (!name) return "none";
+  switch (name.toLowerCase()) {
+    case "blocker":
+    case "critical":
+      return "urgent";
+    case "major":
+      return "high";
+    case "normal":
+    case "minor":
+      return "medium";
+    case "trivial":
+      return "low";
+    default:
+      return "none";
+  }
+}
+
+function toDomain(j: JiraIssue): Issue {
+  const issue: Issue = {
+    ref: `jira:${j.key}`,
+    id: j.id,
+    key: j.key,
+    title: j.fields.summary,
+    description: j.fields.description ?? undefined,
+    status: mapStatusFromJira(j.fields.status.statusCategory?.key),
+    rawStatus: j.fields.status.name,
+    priority: mapPriorityFromJira(j.fields.priority?.name),
+    labels: j.fields.labels?.length ? j.fields.labels : undefined,
+    assignee: j.fields.assignee?.displayName,
+    reporter: j.fields.reporter?.displayName,
+    project: j.fields.project?.key,
+    issueType: j.fields.issuetype?.name,
+    resolution: j.fields.resolution?.name,
+    createdAt: j.fields.created,
+    updatedAt: j.fields.updated,
+  };
+  if (j.fields.parent) {
+    issue.parent = {
+      key: j.fields.parent.key,
+      title: j.fields.parent.fields?.summary ?? "",
+      status: j.fields.parent.fields?.status?.name,
+    };
+  }
+  if (j.self) {
+    const idx = j.self.indexOf("/rest/");
+    if (idx > 0) issue.url = `${j.self.slice(0, idx)}/browse/${j.key}`;
+  }
+  return issue;
+}
+
+function commentToDomain(c: JiraComment): Comment {
+  return {
+    id: c.id,
+    body: c.body,
+    author: c.author?.displayName,
+    createdAt: c.created,
+    updatedAt: c.updated,
+  };
+}