@lsctech/polaris 0.1.0

package/dist/tracker/adapters/github/index.js

@@ -0,0 +1,305 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubIssuesAdapter = void 0;
+const node_https_1 = require("node:https");
+// ──────────────────────────────────────────────────────────────────────────────
+// Internal HTTP helper
+// ──────────────────────────────────────────────────────────────────────────────
+const GITHUB_API_HOSTNAME = "api.github.com";
+const GITHUB_API_VERSION = "2022-11-28";
+const GITHUB_REQUEST_TIMEOUT_MS = 15_000;
+/**
+ * Makes a GitHub REST API request using Node.js built-in `https`.
+ *
+ * @param method  - HTTP method.
+ * @param path    - Request path (e.g. `/repos/owner/repo/issues/1`).
+ * @param token   - GitHub PAT for Bearer authentication.
+ * @param body    - Optional JSON-serializable request body.
+ * @returns Parsed JSON response body, or `null` for 204 No Content.
+ */
+async function githubRequest(method, path, token, body) {
+    const payload = body !== undefined ? JSON.stringify(body) : undefined;
+    return new Promise((resolve, reject) => {
+        const req = (0, node_https_1.request)({
+            hostname: GITHUB_API_HOSTNAME,
+            path,
+            method,
+            headers: {
+                "Accept": "application/vnd.github+json",
+                "Authorization": `Bearer ${token}`,
+                "X-GitHub-Api-Version": GITHUB_API_VERSION,
+                "User-Agent": "polaris-github-adapter",
+                ...(payload !== undefined
+                    ? {
+                        "Content-Type": "application/json",
+                        "Content-Length": Buffer.byteLength(payload),
+                    }
+                    : {}),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => {
+                const statusCode = res.statusCode ?? 0;
+                if (statusCode >= 400) {
+                    const text = Buffer.concat(chunks).toString("utf-8");
+                    reject(new Error(`GitHub API returned ${statusCode} for ${method} ${path}: ${text}`));
+                    return;
+                }
+                // 204 No Content
+                if (statusCode === 204) {
+                    resolve(null);
+                    return;
+                }
+                try {
+                    const text = Buffer.concat(chunks).toString("utf-8");
+                    resolve(JSON.parse(text));
+                }
+                catch (err) {
+                    reject(new Error(`Failed to parse GitHub API response: ${err instanceof Error ? err.message : String(err)}`));
+                }
+            });
+        });
+        req.setTimeout(GITHUB_REQUEST_TIMEOUT_MS, () => {
+            req.destroy(new Error(`GitHub API request timed out after ${GITHUB_REQUEST_TIMEOUT_MS}ms`));
+        });
+        req.on("error", reject);
+        if (payload !== undefined) {
+            req.write(payload);
+        }
+        req.end();
+    });
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Lifecycle state helpers
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Maps a `NormalizedLifecycleState` to the hyphenated label suffix used in
+ * GitHub (e.g. `"in_progress"` → `"in-progress"`).
+ */
+function lifecycleStateToLabelSuffix(state) {
+    return state.replace(/_/g, "-");
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Adapter
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * GitHub Issues tracker adapter.
+ *
+ * Implements {@link CapableTrackerAdapter} against the GitHub REST API v3,
+ * using PAT authentication. Lifecycle states are modelled as open/closed
+ * issue state plus `status:*` labels.
+ *
+ * **Capability summary:**
+ * - Status updates: yes (open/closed + labels)
+ * - Comments: yes
+ * - Lifecycle mapping: yes
+ * - Child relationships, links, dependencies: not supported
+ */
+class GitHubIssuesAdapter {
+    owner;
+    repo;
+    token;
+    labelPrefix;
+    labelPrefixLower;
+    /**
+     * Creates a new `GitHubIssuesAdapter`.
+     *
+     * @param config - GitHub adapter configuration.
+     */
+    constructor(config) {
+        this.owner = config.owner;
+        this.repo = config.repo;
+        this.token = config.token;
+        this.labelPrefix = config.labelPrefix ?? "status:";
+        this.labelPrefixLower = this.labelPrefix.toLowerCase();
+    }
+    // ── CapableTrackerAdapter ──────────────────────────────────────────────────
+    /**
+     * Returns the capabilities supported by the GitHub Issues adapter.
+     */
+    getCapabilities() {
+        return {
+            supportsChildRelationships: false,
+            supportsStatusUpdates: true,
+            supportsComments: true,
+            supportsLinks: false,
+            supportsDependencies: false,
+            supportsLifecycleMapping: true,
+            supportsCreateChild: false,
+        };
+    }
+    /**
+     * Maps a GitHub native status string to a {@link NormalizedLifecycleState}.
+     *
+     * Accepted `nativeStatus` values:
+     * - `"open"` → `"in_progress"` (no status label present)
+     * - `"closed"` → `"done"`
+     * - `"status:in-progress"` → `"in_progress"`
+     * - `"status:in-review"` → `"in_review"`
+     * - `"status:blocked"` → `"blocked"`
+     *
+     * @param nativeStatus - GitHub issue state (`"open"` / `"closed"`) or a
+     *   `status:*` label string.
+     */
+    mapNativeStatus(nativeStatus) {
+        const s = nativeStatus.trim().toLowerCase();
+        if (s === "closed") {
+            return { lifecycleState: "done", supported: true };
+        }
+        if (s === "open") {
+            return { lifecycleState: "in_progress", supported: true };
+        }
+        // Accept status label strings directly (e.g. from stored label names)
+        if (s.startsWith(this.labelPrefixLower)) {
+            const suffix = s.slice(this.labelPrefixLower.length); // e.g. "in-progress"
+            const normalized = suffix.replace(/-/g, "_");
+            const valid = [
+                "backlog",
+                "in_progress",
+                "in_review",
+                "done",
+                "blocked",
+                "cancelled",
+                "no_status_change",
+            ];
+            if (valid.includes(normalized)) {
+                return { lifecycleState: normalized, supported: true };
+            }
+            return {
+                lifecycleState: "no_status_change",
+                supported: false,
+                reason: `Unknown status label suffix '${suffix}' — cannot map to a normalized lifecycle state.`,
+            };
+        }
+        return {
+            lifecycleState: "no_status_change",
+            supported: false,
+            reason: `Unknown GitHub native status '${nativeStatus}'. Expected "open", "closed", or a "${this.labelPrefix}*" label.`,
+        };
+    }
+    /**
+     * Transitions a GitHub issue to a normalized lifecycle state.
+     *
+     * Steps performed:
+     * 1. Fetches the current issue to discover existing `status:*` labels.
+     * 2. Sets issue state to `"closed"` for `"done"` / `"cancelled"`, otherwise
+     *    `"open"`.
+     * 3. Removes all existing `status:*` labels from the issue.
+     * 4. Adds a new `status:<lifecycle-state>` label (hyphens instead of
+     *    underscores).
+     *
+     * Returns `{ applied: false, skipped: true }` when `lifecycleState` is
+     * `"no_status_change"`.
+     *
+     * @param taskId - GitHub issue number as a string (e.g. `"42"`).
+     * @param lifecycleState - Target normalized lifecycle state.
+     * @param _evidence - Unused; accepted for interface compatibility.
+     */
+    async transitionLifecycleState(taskId, lifecycleState, _evidence) {
+        if (lifecycleState === "no_status_change") {
+            return {
+                applied: false,
+                skipped: true,
+                skipReason: "Lifecycle state is 'no_status_change', skipping transition.",
+            };
+        }
+        const basePath = `/repos/${this.owner}/${this.repo}/issues/${taskId}`;
+        try {
+            // 1. Fetch current issue to find existing status labels
+            const issue = await githubRequest("GET", basePath, this.token);
+            const existingStatusLabels = issue.labels
+                .map((l) => l.name)
+                .filter((name) => name.toLowerCase().startsWith(this.labelPrefixLower));
+            // 2. Update open/closed state
+            const newState = lifecycleState === "done" || lifecycleState === "cancelled" ? "closed" : "open";
+            await githubRequest("PATCH", basePath, this.token, { state: newState });
+            // 3. Remove existing status:* labels
+            for (const labelName of existingStatusLabels) {
+                const encodedLabel = encodeURIComponent(labelName);
+                await githubRequest("DELETE", `${basePath}/labels/${encodedLabel}`, this.token);
+            }
+            // 4. Add new status label
+            const newLabel = `${this.labelPrefix}${lifecycleStateToLabelSuffix(lifecycleState)}`;
+            await githubRequest("POST", `${basePath}/labels`, this.token, {
+                labels: [newLabel],
+            });
+            return { applied: true, skipped: false };
+        }
+        catch (err) {
+            return {
+                applied: false,
+                skipped: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    /**
+     * Adds a comment to a GitHub issue.
+     *
+     * @param taskId - GitHub issue number as a string (e.g. `"42"`).
+     * @param body - Markdown comment body.
+     */
+    async addComment(taskId, body) {
+        const path = `/repos/${this.owner}/${this.repo}/issues/${taskId}/comments`;
+        try {
+            await githubRequest("POST", path, this.token, { body });
+            return { added: true, unsupported: false };
+        }
+        catch (err) {
+            return {
+                added: false,
+                unsupported: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    /**
+     * Link attachments are not supported by the GitHub Issues API.
+     *
+     * Always returns `{ attached: false, unsupported: true }`.
+     *
+     * @param _taskId - Unused.
+     * @param _url - Unused.
+     * @param _title - Unused.
+     */
+    async attachLink(_taskId, _url, _title) {
+        return {
+            attached: false,
+            unsupported: true,
+            reason: "GitHub Issues does not support native link attachments.",
+        };
+    }
+    /**
+     * Dependency relations are not supported by the GitHub Issues API.
+     *
+     * Always returns `{ added: false, unsupported: true }`.
+     *
+     * @param _taskId - Unused.
+     * @param _dependsOnTaskId - Unused.
+     */
+    async addDependency(_taskId, _dependsOnTaskId) {
+        return {
+            added: false,
+            unsupported: true,
+            reason: "GitHub Issues does not support native dependency relations.",
+        };
+    }
+    /**
+     * Child issue creation is not supported by the GitHub Issues adapter.
+     *
+     * Always returns `{ created: false, unsupported: true }`.
+     *
+     * @param _parentId - Unused.
+     * @param _title - Unused.
+     * @param _body - Unused.
+     */
+    async createChild(_parentId, _title, _body) {
+        return {
+            created: false,
+            unsupported: true,
+            reason: "GitHub Issues adapter does not support creating child issues.",
+        };
+    }
+}
+exports.GitHubIssuesAdapter = GitHubIssuesAdapter;

package/dist/tracker/adapters/jira/index.js

@@ -0,0 +1,293 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JiraCloudAdapter = void 0;
+const node_https_1 = require("node:https");
+const JIRA_REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Performs an HTTPS request against the Jira Cloud REST API v3.
+ *
+ * @param config - Adapter config providing baseUrl and credentials.
+ * @param method - HTTP method ("GET" or "POST").
+ * @param path - API path, e.g. "/rest/api/3/issue/FOO-1/transitions".
+ * @param body - Optional request body. Will be JSON-serialized when provided.
+ * @returns Parsed JSON response body.
+ * @throws On HTTP 4xx/5xx or JSON parse failure.
+ */
+function jiraRequest(config, method, path, body) {
+    const auth = Buffer.from(`${config.email}:${config.apiToken}`).toString("base64");
+    const url = new URL(config.baseUrl);
+    const payload = body !== undefined ? JSON.stringify(body) : undefined;
+    return new Promise((resolve, reject) => {
+        const options = {
+            hostname: url.hostname,
+            port: url.port || undefined,
+            path,
+            method,
+            headers: {
+                Authorization: `Basic ${auth}`,
+                Accept: "application/json",
+                ...(payload !== undefined
+                    ? { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(payload) }
+                    : {}),
+            },
+        };
+        const req = (0, node_https_1.request)(options, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => {
+                const responseBody = Buffer.concat(chunks).toString("utf-8");
+                if ((res.statusCode ?? 0) >= 400) {
+                    reject(new Error(`Jira API returned ${res.statusCode}: ${responseBody || "<empty response body>"}`));
+                    return;
+                }
+                if (!responseBody) {
+                    resolve(undefined);
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(responseBody));
+                }
+                catch {
+                    reject(new Error(`Jira API returned non-JSON response: ${responseBody}`));
+                }
+            });
+        });
+        req.setTimeout(JIRA_REQUEST_TIMEOUT_MS, () => {
+            req.destroy(new Error(`Jira API request timed out after ${JIRA_REQUEST_TIMEOUT_MS}ms`));
+        });
+        req.on("error", reject);
+        if (payload !== undefined) {
+            req.write(payload);
+        }
+        req.end();
+    });
+}
+/**
+ * Heuristic mapping from lowercased Jira status names to normalized lifecycle states.
+ * Returns `undefined` when no match is found.
+ */
+function heuristicMap(normalizedName) {
+    if (["to do", "backlog", "new", "open"].includes(normalizedName)) {
+        return "backlog";
+    }
+    if (["in progress", "in development", "started", "doing"].includes(normalizedName)) {
+        return "in_progress";
+    }
+    if (["in review", "under review", "ready for review", "in qa", "in testing"].includes(normalizedName)) {
+        return "in_review";
+    }
+    if (["done", "completed", "resolved", "closed", "ready for deployment"].includes(normalizedName)) {
+        return "done";
+    }
+    if (["blocked", "on hold", "waiting", "paused"].includes(normalizedName)) {
+        return "blocked";
+    }
+    if (["cancelled", "canceled", "won't do", "duplicate", "invalid"].includes(normalizedName)) {
+        return "cancelled";
+    }
+    return undefined;
+}
+/**
+ * Tracker adapter for Jira Cloud using the REST API v3 with Basic Auth.
+ *
+ * Implements `CapableTrackerAdapter` to provide lifecycle state transitions,
+ * comment posting, and status mapping against a Jira Cloud project.
+ */
+class JiraCloudAdapter {
+    config;
+    /**
+     * Creates a new JiraCloudAdapter.
+     *
+     * @param config - Jira Cloud connection and project configuration.
+     */
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Returns the capabilities supported by the Jira Cloud adapter.
+     */
+    getCapabilities() {
+        return {
+            supportsChildRelationships: false,
+            supportsStatusUpdates: true,
+            supportsComments: true,
+            supportsLinks: false,
+            supportsDependencies: false,
+            supportsLifecycleMapping: true,
+            supportsCreateChild: false,
+        };
+    }
+    /**
+     * Maps a Jira status name to a normalized lifecycle state, consulting
+     * user-configured `statusMappings` before falling back to the built-in
+     * heuristic.
+     *
+     * @param statusName - The native Jira status name (case-insensitive).
+     * @returns The matching normalized lifecycle state, or `undefined` if unknown.
+     */
+    mapStatusToLifecycle(statusName) {
+        const normalizedName = statusName.toLowerCase().trim();
+        if (this.config.statusMappings) {
+            for (const [key, value] of Object.entries(this.config.statusMappings)) {
+                if (key.toLowerCase().trim() === normalizedName) {
+                    return value;
+                }
+            }
+        }
+        return heuristicMap(normalizedName);
+    }
+    /**
+     * Maps a native Jira status name to a normalized lifecycle state.
+     *
+     * User-provided `statusMappings` in the adapter config override the built-in
+     * heuristic for any matching status name (case-insensitive).
+     *
+     * @param nativeStatus - The native Jira status name (e.g. "In Progress").
+     * @returns A status mapping result with the normalized state and support status.
+     */
+    mapNativeStatus(nativeStatus) {
+        const mapped = this.mapStatusToLifecycle(nativeStatus);
+        if (mapped !== undefined) {
+            return { lifecycleState: mapped, supported: true };
+        }
+        return {
+            lifecycleState: "no_status_change",
+            supported: false,
+            reason: `Unknown Jira status '${nativeStatus}'. Consider adding an explicit statusMappings override.`,
+        };
+    }
+    /**
+     * Attempts to transition a Jira issue to the target lifecycle state.
+     *
+     * Fetches available transitions from the Jira API, finds one whose name
+     * heuristically maps to the requested lifecycle state, and applies it.
+     *
+     * @param taskId - The Jira issue key or ID (e.g. "POL-42").
+     * @param lifecycleState - The target normalized lifecycle state.
+     * @param _evidence - Unused. Present for interface compatibility.
+     * @returns A lifecycle transition result indicating success, skip, or failure.
+     */
+    async transitionLifecycleState(taskId, lifecycleState, _evidence) {
+        if (lifecycleState === "no_status_change") {
+            return {
+                applied: false,
+                skipped: true,
+                skipReason: "Lifecycle state is 'no_status_change', skipping transition",
+            };
+        }
+        let transitionsData;
+        try {
+            transitionsData = (await jiraRequest(this.config, "GET", `/rest/api/3/issue/${taskId}/transitions`));
+        }
+        catch (err) {
+            return {
+                applied: false,
+                skipped: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+        const transitions = transitionsData?.transitions ?? [];
+        // Find a transition whose name maps to the target lifecycle state (respects statusMappings).
+        const match = transitions.find((t) => this.mapStatusToLifecycle(t.name) === lifecycleState);
+        if (!match) {
+            return {
+                applied: false,
+                skipped: true,
+                skipReason: `No Jira transition found that maps to lifecycle state '${lifecycleState}' for issue '${taskId}'.`,
+            };
+        }
+        try {
+            await jiraRequest(this.config, "POST", `/rest/api/3/issue/${taskId}/transitions`, {
+                transition: { id: match.id },
+            });
+        }
+        catch (err) {
+            return {
+                applied: false,
+                skipped: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+        return { applied: true, skipped: false };
+    }
+    /**
+     * Adds a comment to a Jira issue using the Atlassian Document Format (ADF).
+     *
+     * @param taskId - The Jira issue key or ID (e.g. "POL-42").
+     * @param body - The plain-text comment body.
+     * @returns A comment result indicating success or failure.
+     */
+    async addComment(taskId, body) {
+        const adfBody = {
+            body: {
+                type: "doc",
+                version: 1,
+                content: [
+                    {
+                        type: "paragraph",
+                        content: [{ type: "text", text: body }],
+                    },
+                ],
+            },
+        };
+        try {
+            await jiraRequest(this.config, "POST", `/rest/api/3/issue/${taskId}/comment`, adfBody);
+        }
+        catch (err) {
+            return {
+                added: false,
+                unsupported: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+        return { added: true, unsupported: false };
+    }
+    /**
+     * Attaching arbitrary URL links is not supported by this adapter.
+     *
+     * Jira has issue links but not arbitrary URL attachments. Use `addComment`
+     * to include URLs in issue comments instead.
+     *
+     * @param _taskId - Unused.
+     * @param _url - Unused.
+     * @param _title - Unused.
+     * @returns A link result indicating the operation is unsupported.
+     */
+    async attachLink(_taskId, _url, _title) {
+        return {
+            attached: false,
+            unsupported: true,
+            reason: "Jira Cloud adapter does not support arbitrary URL link attachments. Use addComment to include URLs.",
+        };
+    }
+    /**
+     * Dependency relations are not supported by this adapter.
+     *
+     * @param _taskId - Unused.
+     * @param _dependsOnTaskId - Unused.
+     * @returns A dependency result indicating the operation is unsupported.
+     */
+    async addDependency(_taskId, _dependsOnTaskId) {
+        return {
+            added: false,
+            unsupported: true,
+            reason: "Jira Cloud adapter does not support dependency relations via this interface.",
+        };
+    }
+    /**
+     * Creating child tasks is not supported by this adapter.
+     *
+     * @param _parentId - Unused.
+     * @param _title - Unused.
+     * @param _body - Unused.
+     * @returns A create child result indicating the operation is unsupported.
+     */
+    async createChild(_parentId, _title, _body) {
+        return {
+            created: false,
+            unsupported: true,
+            reason: "Jira Cloud adapter does not support creating child issues via this interface.",
+        };
+    }
+}
+exports.JiraCloudAdapter = JiraCloudAdapter;

package/dist/tracker/adapters/linear/http-errors.test.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_events_1 = require("node:events");
+const vitest_1 = require("vitest");
+const requestMock = vitest_1.vi.hoisted(() => vitest_1.vi.fn());
+vitest_1.vi.mock("node:https", () => ({
+    request: requestMock,
+}));
+(0, vitest_1.describe)("LinearAdapter HTTP error handling", () => {
+    const originalApiKey = process.env["LINEAR_API_KEY"];
+    (0, vitest_1.beforeEach)(() => {
+        requestMock.mockReset();
+    });
+    (0, vitest_1.it)("includes non-2xx response body in thrown error", async () => {
+        process.env["LINEAR_API_KEY"] = "linear-test-token";
+        requestMock.mockImplementation((_options, callback) => {
+            const req = new node_events_1.EventEmitter();
+            req.write = vitest_1.vi.fn();
+            req.end = vitest_1.vi.fn(() => {
+                const res = new node_events_1.EventEmitter();
+                res.statusCode = 400;
+                callback(res);
+                res.emit("data", Buffer.from(JSON.stringify({ errors: [{ message: "bad query" }] })));
+                res.emit("end");
+            });
+            req.on = req.addListener.bind(req);
+            return req;
+        });
+        try {
+            vitest_1.vi.resetModules();
+            const { LinearAdapter } = await import("./index.js");
+            const config = {
+                tracker: {
+                    linear: {
+                        enabled: true,
+                    },
+                },
+            };
+            const adapter = new LinearAdapter(config);
+            await (0, vitest_1.expect)(adapter.syncIn("POL-198")).rejects.toThrow("Linear API returned 400: {\"errors\":[{\"message\":\"bad query\"}]}");
+        }
+        finally {
+            if (originalApiKey === undefined) {
+                delete process.env["LINEAR_API_KEY"];
+            }
+            else {
+                process.env["LINEAR_API_KEY"] = originalApiKey;
+            }
+        }
+    });
+});