@mndrk/agx 2.3.3 → 2.4.1

package/cloud-runtime/standalone/apps/local/lib/tracker/adapters/linear/index.ts

@@ -0,0 +1,9 @@
+// Linear adapter barrel export
+
+export { LinearClient, getLinearClient, getProjectTicketToken, saveProjectTicketToken, deleteProjectTicketToken } from "./client";
+export type { LinearToken, TicketProviderToken, LinearUser, LinearTeam, LinearCycle, LinearIssueLabel, CreateLinearIssueLabelInput, CreateLinearIssueInput, CreatedLinearIssue, LinearIssueNode } from "./client";
+export { LinearAdapter } from "./adapter";
+
+// Re-export the issue functions for backward compatibility during migration
+export { pullLinearIssues, ensureLinearIssueCache, listLinearIssueSummaries, getLinearIssueContexts } from "./issues";
+export type { LinearIssueSummary, LinearIssueContext, EnsureLinearIssueCacheInput, PullLinearIssuesResult } from "./issues";

package/cloud-runtime/standalone/apps/local/lib/tracker/adapters/linear/issues.ts

@@ -0,0 +1,376 @@
+import "server-only";
+
+// TODO(multi-tracker): This file fetches and caches issues from Linear.
+// Abstraction path: extract a `TicketFetcher` interface (pullIssues, listIssues, getIssueContext)
+// and move the Linear-specific GraphQL calls behind a `LinearTicketFetcher` implementation.
+// The cache in linear-issue-store.ts should grow a `tracker_type` column so Linear and Jira
+// issues can coexist in the same SQLite table.
+
+import fs from "node:fs";
+import path from "node:path";
+import { dump } from "js-yaml";
+import { getLinearClient } from "./client";
+import {
+  countCachedTrackerItems as countCachedLinearIssues,
+  getCachedTrackerItemContexts as getCachedLinearIssueContexts,
+  getTrackerItemSyncState as getLinearIssueSyncState,
+  listCachedTrackerItems as listCachedLinearIssues,
+  replaceCachedTrackerItems as replaceCachedLinearIssues,
+  setTrackerItemSyncState as setLinearIssueSyncState,
+  type CachedTrackerItemInput as CachedLinearIssueInput,
+  type CachedTrackerItemRecord as CachedLinearIssueRecord,
+  type ListCachedTrackerItemsInput as ListCachedLinearIssuesInput,
+} from "../../tracker-item-store";
+import { vaultStore } from "@/lib/vault-store";
+
+const GLOBAL_SCOPE_KEY = "global";
+const MAX_PULL_ISSUES = 500;
+const PULL_PAGE_SIZE = 100;
+
+export interface LinearIssueSummary {
+  id: string;
+  identifier: string;
+  title: string;
+  url: string | null;
+  status: string;
+  assignee: string | null;
+  updatedAt: string;
+  labels?: string[];
+}
+
+export interface LinearIssueContext extends LinearIssueSummary {
+  description: string | null;
+  assigneeId: string | null;
+  assigneeEmail: string | null;
+  isAssignedToMe: boolean;
+  teamId: string | null;
+  teamName: string | null;
+  teamKey: string | null;
+  cycleId: string | null;
+  cycleName: string | null;
+  cycleNumber: number | null;
+  pulledAt: string;
+}
+
+export interface EnsureLinearIssueCacheInput {
+  projectId: string;
+  refresh?: boolean;
+  projectSlug?: string | null;
+}
+
+export interface PullLinearIssuesResult {
+  issueCount: number;
+  complete: boolean;
+  pulledAt: string;
+}
+
+function toScopeKey(projectSlug?: string | null): string {
+  const normalized = String(projectSlug ?? "").trim().toLowerCase();
+  return normalized ? `project:${normalized}` : GLOBAL_SCOPE_KEY;
+}
+
+function ensureDir(dirPath: string): void {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function atomicWriteText(filePath: string, content: string): void {
+  ensureDir(path.dirname(filePath));
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tempPath, content, "utf8");
+  fs.renameSync(tempPath, filePath);
+}
+
+function normalizeMarkdownBody(content: string): string {
+  return String(content || "")
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .map((line) => line.replace(/\s+$/g, ""))
+    .join("\n")
+    .trim();
+}
+
+function writeMarkdownFile(filePath: string, frontmatter: Record<string, unknown>, body: string): void {
+  const yaml = dump(frontmatter, { lineWidth: 120, noRefs: true, sortKeys: true }).trimEnd();
+  const normalizedBody = normalizeMarkdownBody(body);
+  const content = normalizedBody
+    ? `---\n${yaml}\n---\n${normalizedBody}\n`
+    : `---\n${yaml}\n---\n`;
+  atomicWriteText(filePath, content);
+}
+
+function toSummary(issue: CachedLinearIssueRecord): LinearIssueSummary {
+  return {
+    id: issue.id,
+    identifier: issue.identifier,
+    title: issue.title,
+    url: issue.url,
+    status: issue.status,
+    assignee: issue.assignee,
+    updatedAt: issue.updatedAt,
+    labels: issue.labels ?? [],
+  };
+}
+
+function toContext(issue: CachedLinearIssueRecord): LinearIssueContext {
+  return {
+    ...toSummary(issue),
+    description: issue.description,
+    assigneeId: issue.assigneeId,
+    assigneeEmail: issue.assigneeEmail,
+    isAssignedToMe: issue.isAssignedToMe,
+    teamId: issue.teamId,
+    teamName: issue.teamName,
+    teamKey: issue.teamKey,
+    cycleId: issue.cycleId,
+    cycleName: issue.cycleName,
+    cycleNumber: issue.cycleNumber,
+    pulledAt: issue.pulledAt,
+  };
+}
+
+function sanitizeIssueDirectoryName(identifier: string, fallback: string): string {
+  const normalized = identifier.trim().replace(/[\\/]/g, "-");
+  return normalized || fallback;
+}
+
+function resolveVaultIssuesRoot(projectSlug?: string | null): string {
+  const rootDir = vaultStore.getRootDir();
+  const normalizedProjectSlug = String(projectSlug ?? "").trim();
+
+  if (normalizedProjectSlug) {
+    const project = vaultStore.getProjectWithRepos(normalizedProjectSlug);
+    const resolvedSlug = project?.slug ?? normalizedProjectSlug;
+    return path.join(rootDir, resolvedSlug, "issues");
+  }
+
+  return path.join(rootDir, "_global", "Linear", "issues");
+}
+
+function issueMarkdownBody(issue: CachedLinearIssueInput, pulledAt: string): string {
+  const lines = [
+    `# ${issue.identifier}: ${issue.title}`,
+    "",
+    `- Status: ${issue.status}`,
+    `- Assignee: ${issue.assignee ?? "Unassigned"}`,
+    issue.teamName ? `- Team: ${issue.teamName}` : null,
+    issue.cycleName || issue.cycleNumber != null
+      ? `- Cycle: ${issue.cycleName ?? `Cycle ${issue.cycleNumber}`}`
+      : null,
+    issue.labels?.length ? `- Labels: ${issue.labels.join(", ")}` : null,
+    `- Updated in Linear: ${issue.updatedAt}`,
+    `- Pulled locally: ${pulledAt}`,
+    issue.url ? `- URL: ${issue.url}` : null,
+    "",
+    "## Description",
+    "",
+    issue.description?.trim() || "_No description provided._",
+  ];
+
+  return lines.filter((line): line is string => line !== null).join("\n");
+}
+
+function writeLinearIssuesToVault(
+  issues: CachedLinearIssueInput[],
+  pulledAt: string,
+  projectSlug?: string | null
+): void {
+  const issuesRoot = resolveVaultIssuesRoot(projectSlug);
+  ensureDir(issuesRoot);
+
+  const indexLines = [
+    "# Linear Issues",
+    "",
+    `Last pulled: ${pulledAt}`,
+    "",
+  ];
+
+  for (const issue of issues) {
+    const issueDir = path.join(
+      issuesRoot,
+      sanitizeIssueDirectoryName(issue.identifier, issue.id)
+    );
+    writeMarkdownFile(
+      path.join(issueDir, "README.md"),
+      {
+        type: "linear-issue",
+        issue_id: issue.id,
+        identifier: issue.identifier,
+        title: issue.title,
+        status: issue.status,
+        assignee_id: issue.assigneeId ?? null,
+        assignee_name: issue.assignee ?? null,
+        assignee_email: issue.assigneeEmail ?? null,
+        team_id: issue.teamId ?? null,
+        team_name: issue.teamName ?? null,
+        team_key: issue.teamKey ?? null,
+        cycle_id: issue.cycleId ?? null,
+        cycle_name: issue.cycleName ?? null,
+        cycle_number: issue.cycleNumber ?? null,
+        url: issue.url ?? null,
+        updated_at: issue.updatedAt,
+        pulled_at: pulledAt,
+      },
+      issueMarkdownBody(issue, pulledAt)
+    );
+
+    indexLines.push(
+      `- [${issue.identifier}](${encodeURIComponent(
+        sanitizeIssueDirectoryName(issue.identifier, issue.id)
+      )}/README.md) - ${issue.title} (${issue.status})`
+    );
+  }
+
+  atomicWriteText(path.join(issuesRoot, "_index.md"), `${indexLines.join("\n")}\n`);
+}
+
+export async function pullLinearIssues(input: {
+  projectId: string;
+  projectSlug?: string | null;
+}): Promise<PullLinearIssuesResult> {
+  const client = getLinearClient(input.projectId);
+  if (!client) {
+    throw new Error("Not connected");
+  }
+
+  const viewer = await client.viewer;
+  const pulledAtMs = Date.now();
+  const pulledAt = new Date(pulledAtMs).toISOString();
+
+  let after: string | undefined;
+  let totalFetched = 0;
+  let complete = true;
+  const issues: CachedLinearIssueInput[] = [];
+
+  while (totalFetched < MAX_PULL_ISSUES) {
+    const remaining = MAX_PULL_ISSUES - totalFetched;
+    const result = await client.issues({
+      first: Math.min(PULL_PAGE_SIZE, remaining),
+      after,
+      orderBy: "updatedAt" as const,
+    });
+
+    const pageIssues = await Promise.all(
+      result.nodes.map(async (issue) => {
+        const [labels, state, assignee, team, cycle] = await Promise.all([
+          issue.labels,
+          issue.state,
+          issue.assignee,
+          issue.team,
+          issue.cycle,
+        ]);
+
+        return {
+          id: issue.id,
+          trackerType: "linear",
+          trackerId: issue.id,
+          identifier: issue.identifier,
+          title: issue.title,
+          description: issue.description ?? null,
+          labels,
+          url: issue.url,
+          status: state?.name ?? "Unknown",
+          assigneeId: assignee?.id ?? null,
+          assignee: assignee?.name ?? null,
+          assigneeEmail: assignee?.email ?? null,
+          isAssignedToMe: Boolean(assignee?.id && assignee.id === viewer.id),
+          teamId: team?.id ?? null,
+          teamName: team?.name ?? null,
+          teamKey: team?.key ?? null,
+          cycleId: cycle?.id ?? null,
+          cycleName: cycle?.name ?? null,
+          cycleNumber: cycle?.number ?? null,
+          updatedAt: issue.updatedAt,
+        } satisfies CachedLinearIssueInput;
+      })
+    );
+
+    issues.push(...pageIssues);
+    totalFetched += pageIssues.length;
+
+    if (!result.pageInfo.hasNextPage || !result.pageInfo.endCursor) {
+      break;
+    }
+
+    if (totalFetched >= MAX_PULL_ISSUES) {
+      complete = false;
+      break;
+    }
+
+    after = result.pageInfo.endCursor;
+  }
+
+  await replaceCachedLinearIssues({
+    trackerType: "linear",
+    issues,
+    complete,
+    pulledAtMs,
+  });
+  await setLinearIssueSyncState(GLOBAL_SCOPE_KEY, issues.length, pulledAtMs);
+
+  const projectScopeKey = toScopeKey(input.projectSlug);
+  if (projectScopeKey !== GLOBAL_SCOPE_KEY) {
+    await setLinearIssueSyncState(projectScopeKey, issues.length, pulledAtMs);
+  }
+
+  writeLinearIssuesToVault(issues, pulledAt, input.projectSlug);
+
+  return {
+    issueCount: issues.length,
+    complete,
+    pulledAt,
+  };
+}
+
+export async function ensureLinearIssueCache(
+  input: EnsureLinearIssueCacheInput
+): Promise<PullLinearIssuesResult | null> {
+  const refresh = Boolean(input.refresh);
+  const scopeKey = toScopeKey(input.projectSlug);
+
+  if (!refresh) {
+    const [issueCount, scopeState] = await Promise.all([
+      countCachedLinearIssues(),
+      getLinearIssueSyncState(scopeKey),
+    ]);
+
+    if (issueCount > 0 && scopeState) {
+      return null;
+    }
+  }
+
+  const client = getLinearClient(input.projectId);
+  if (!client) {
+    return null;
+  }
+
+  return pullLinearIssues({ projectId: input.projectId, projectSlug: input.projectSlug });
+}
+
+export async function listLinearIssueSummaries(
+  input: ListCachedLinearIssuesInput = {}
+): Promise<{
+  issues: LinearIssueSummary[];
+  pageInfo: {
+    hasNextPage: boolean;
+    endCursor: string | null;
+  };
+  syncState: { lastPulledAt: string | null };
+}> {
+  const [result, syncState] = await Promise.all([
+    listCachedLinearIssues(input),
+    getLinearIssueSyncState(GLOBAL_SCOPE_KEY),
+  ]);
+
+  return {
+    issues: result.issues.map(toSummary),
+    pageInfo: result.pageInfo,
+    syncState: {
+      lastPulledAt: syncState?.lastPulledAt ?? null,
+    },
+  };
+}
+
+export async function getLinearIssueContexts(issueIds: string[]): Promise<LinearIssueContext[]> {
+  const issues = await getCachedLinearIssueContexts(issueIds);
+  return issues.map(toContext);
+}

package/cloud-runtime/standalone/apps/local/lib/tracker/adapters/linear/linear-icon.tsx

@@ -0,0 +1,14 @@
+// Client-safe LinearIcon component — no server-only imports.
+// Official Linear logomark from Simple Icons.
+export function LinearIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="M2.886 4.18A11.982 11.982 0 0 1 11.99 0C18.624 0 24 5.376 24 12.009c0 3.64-1.62 6.903-4.18 9.105L2.887 4.18ZM1.817 5.626l16.556 16.556c-.524.33-1.075.62-1.65.866L.951 7.277c.247-.575.537-1.126.866-1.65ZM.322 9.163l14.515 14.515c-.71.172-1.443.282-2.195.322L0 11.358a12 12 0 0 1 .322-2.195Zm-.17 4.862 9.823 9.824a12.02 12.02 0 0 1-9.824-9.824Z" />
+    </svg>
+  );
+}

package/cloud-runtime/standalone/apps/local/lib/tracker/connections.ts

@@ -0,0 +1,67 @@
+import "server-only";
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import type { TrackerConnection } from "./types";
+
+const AGX_DIR = path.join(homedir(), ".agx");
+
+function getConnectionsPath(projectId: string): string {
+  return path.join(AGX_DIR, "projects", projectId, "integrations", "trackers.json");
+}
+
+function ensureDir(filePath: string): void {
+  const dir = path.dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+export function listTrackerConnections(projectId: string): TrackerConnection[] {
+  if (!projectId) return [];
+  const filePath = getConnectionsPath(projectId);
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    const data = JSON.parse(raw);
+    return Array.isArray(data.connections) ? data.connections : [];
+  } catch {
+    return [];
+  }
+}
+
+export function addTrackerConnection(
+  projectId: string,
+  connection: TrackerConnection
+): void {
+  if (!projectId) return;
+  const filePath = getConnectionsPath(projectId);
+  ensureDir(filePath);
+  const connections = listTrackerConnections(projectId);
+  // Prevent duplicates — update existing connection of same type
+  const existing = connections.findIndex((c) => c.type === connection.type);
+  if (existing >= 0) {
+    connections[existing] = connection;
+  } else {
+    connections.push(connection);
+  }
+  writeFileSync(filePath, JSON.stringify({ connections }, null, 2), "utf8");
+}
+
+export function removeTrackerConnection(projectId: string, trackerType: string): void {
+  if (!projectId) return;
+  const filePath = getConnectionsPath(projectId);
+  const connections = listTrackerConnections(projectId).filter(
+    (c) => c.type !== trackerType
+  );
+  if (connections.length === 0) {
+    try {
+      unlinkSync(filePath);
+    } catch {
+      // already gone
+    }
+  } else {
+    ensureDir(filePath);
+    writeFileSync(filePath, JSON.stringify({ connections }, null, 2), "utf8");
+  }
+}

package/cloud-runtime/standalone/apps/local/lib/tracker/index.ts

@@ -0,0 +1,44 @@
+// Tracker module barrel export.
+// Importing this file registers all built-in adapters.
+
+import { registerAdapter } from "./registry";
+import { LinearAdapter } from "./adapters/linear";
+import { JiraAdapter } from "./adapters/jira";
+
+// Register all built-in adapters
+const linearAdapter = new LinearAdapter();
+registerAdapter(linearAdapter);
+
+const jiraAdapter = new JiraAdapter();
+registerAdapter(jiraAdapter);
+
+// Re-export public API
+export { getAdapter, getAdapterOrNull, listAdapterTypes, listAdapters } from "./registry";
+export { listTrackerConnections, addTrackerConnection, removeTrackerConnection } from "./connections";
+export type { TrackerAdapter, McpServerConfig } from "./tracker-adapter";
+export type {
+  TrackerItem,
+  TrackerItemDetail,
+  TrackerGroup,
+  TrackerComment,
+  TrackerActivity,
+  TrackerStatusCategory,
+  TrackerFilters,
+  TrackerItemUpdate,
+  TrackerStatusOption,
+  TrackerAssignee,
+  ConnectionStatus,
+  TokenResult,
+  TrackerConnection,
+  PaginatedResult,
+  TrackerRunMode,
+  TrackerRunStatus,
+} from "./types";
+export type { TrackerRunRecord, IssueActiveAgent } from "./tracker-run-store";
+export type {
+  CachedTrackerItemRecord,
+  CachedTrackerItemInput,
+  TrackerItemSyncState,
+  ListCachedTrackerItemsInput,
+  ListCachedTrackerItemsResult,
+} from "./tracker-item-store";