@useatlas/create 0.0.1

package/templates/docker/src/lib/tools/actions/__tests__/jira.test.ts

@@ -0,0 +1,427 @@
+import { describe, it, expect, beforeEach, afterEach, mock } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mock handler module so we don't hit real DB / auth
+// ---------------------------------------------------------------------------
+
+let lastHandleActionCall: { request: unknown; executeFn: unknown } | null = null;
+
+mock.module("@atlas/api/lib/tools/actions/handler", () => ({
+  buildActionRequest: (params: Record<string, unknown>) => ({
+    id: "test-action-id",
+    ...params,
+  }),
+  handleAction: async (request: unknown, executeFn: unknown) => {
+    lastHandleActionCall = { request, executeFn };
+    return { status: "pending_approval", actionId: "test-action-id", summary: "test" };
+  },
+}));
+
+mock.module("@atlas/api/lib/logger", () => ({
+  createLogger: () => ({
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+  }),
+}));
+
+const { executeJiraCreate, createJiraTicket, textToADF } = await import(
+  "@atlas/api/lib/tools/actions/jira"
+);
+
+// ---------------------------------------------------------------------------
+// Env snapshot + fetch mock
+// ---------------------------------------------------------------------------
+
+const ENV_KEYS = [
+  "JIRA_BASE_URL",
+  "JIRA_EMAIL",
+  "JIRA_API_TOKEN",
+  "JIRA_DEFAULT_PROJECT",
+] as const;
+
+const saved: Record<string, string | undefined> = {};
+const originalFetch = globalThis.fetch;
+
+let capturedFetchUrl = "";
+let capturedFetchInit: RequestInit | undefined;
+
+function installFetchMock(
+  response: { status: number; body: unknown },
+) {
+  globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    capturedFetchUrl = typeof input === "string" ? input : (input as Request).url;
+    capturedFetchInit = init;
+    return new Response(JSON.stringify(response.body), {
+      status: response.status,
+      headers: { "Content-Type": "application/json" },
+    });
+  }) as typeof globalThis.fetch;
+}
+
+function installFetchMockRaw(
+  response: { status: number; text: string },
+) {
+  globalThis.fetch = (async (input: string | URL | Request) => {
+    capturedFetchUrl = typeof input === "string" ? input : (input as Request).url;
+    return new Response(response.text, { status: response.status });
+  }) as typeof globalThis.fetch;
+}
+
+beforeEach(() => {
+  for (const key of ENV_KEYS) saved[key] = process.env[key];
+  lastHandleActionCall = null;
+  capturedFetchUrl = "";
+  capturedFetchInit = undefined;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  for (const key of ENV_KEYS) {
+    if (saved[key] !== undefined) process.env[key] = saved[key];
+    else delete process.env[key];
+  }
+});
+
+// ---------------------------------------------------------------------------
+// AtlasAction metadata
+// ---------------------------------------------------------------------------
+
+describe("createJiraTicket — metadata", () => {
+  it("has the correct actionType", () => {
+    expect(createJiraTicket.actionType).toBe("jira:create");
+  });
+
+  it("is reversible", () => {
+    expect(createJiraTicket.reversible).toBe(true);
+  });
+
+  it("defaults to manual approval", () => {
+    expect(createJiraTicket.defaultApproval).toBe("manual");
+  });
+
+  it("requires JIRA credentials", () => {
+    expect(createJiraTicket.requiredCredentials).toEqual([
+      "JIRA_BASE_URL",
+      "JIRA_EMAIL",
+      "JIRA_API_TOKEN",
+    ]);
+  });
+
+  it("has a name", () => {
+    expect(createJiraTicket.name).toBe("createJiraTicket");
+  });
+
+  it("has a description", () => {
+    expect(createJiraTicket.description).toBeTruthy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// textToADF — Atlassian Document Format helper
+// ---------------------------------------------------------------------------
+
+describe("textToADF", () => {
+  it("splits multi-paragraph text into separate paragraph nodes", () => {
+    const doc = textToADF("Para1\n\nPara2\n\nPara3");
+    expect(doc.type).toBe("doc");
+    expect(doc.version).toBe(1);
+    expect(doc.content).toHaveLength(3);
+    expect(doc.content[0].content[0].text).toBe("Para1");
+    expect(doc.content[1].content[0].text).toBe("Para2");
+    expect(doc.content[2].content[0].text).toBe("Para3");
+  });
+
+  it("returns fallback for empty text", () => {
+    const doc = textToADF("");
+    expect(doc.content).toHaveLength(1);
+    expect(doc.content[0].content[0].text).toBe("(no description)");
+  });
+
+  it("returns fallback for whitespace-only text", () => {
+    const doc = textToADF("   \n\n   ");
+    expect(doc.content).toHaveLength(1);
+    expect(doc.content[0].content[0].text).toBe("(no description)");
+  });
+
+  it("produces no empty paragraph nodes from trailing newlines", () => {
+    const doc = textToADF("Hello\n\n\n\n");
+    for (const node of doc.content) {
+      expect(node.content[0].text.trim().length).toBeGreaterThan(0);
+    }
+    expect(doc.content).toHaveLength(1);
+    expect(doc.content[0].content[0].text).toBe("Hello");
+  });
+
+  it("does not split on single newlines", () => {
+    const doc = textToADF("Line1\nLine2");
+    expect(doc.content).toHaveLength(1);
+    expect(doc.content[0].content[0].text).toBe("Line1\nLine2");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// executeJiraCreate — raw API call
+// ---------------------------------------------------------------------------
+
+describe("executeJiraCreate", () => {
+  it("throws when JIRA credentials are missing", async () => {
+    delete process.env.JIRA_BASE_URL;
+    delete process.env.JIRA_EMAIL;
+    delete process.env.JIRA_API_TOKEN;
+
+    await expect(
+      executeJiraCreate({
+        summary: "Test",
+        description: "Test desc",
+        project: "PROJ",
+      }),
+    ).rejects.toThrow("Missing JIRA credentials");
+  });
+
+  it("throws when no project is specified and no default", async () => {
+    process.env.JIRA_BASE_URL = "https://test.atlassian.net";
+    process.env.JIRA_EMAIL = "test@example.com";
+    process.env.JIRA_API_TOKEN = "tok-123";
+    delete process.env.JIRA_DEFAULT_PROJECT;
+
+    await expect(
+      executeJiraCreate({
+        summary: "Test",
+        description: "Test desc",
+      }),
+    ).rejects.toThrow("No JIRA project specified");
+  });
+
+  it("calls the correct JIRA API endpoint with Basic auth", async () => {
+    process.env.JIRA_BASE_URL = "https://test.atlassian.net";
+    process.env.JIRA_EMAIL = "test@example.com";
+    process.env.JIRA_API_TOKEN = "tok-123";
+
+    installFetchMock({
+      status: 201,
+      body: { key: "PROJ-42", self: "https://test.atlassian.net/rest/api/3/issue/12345" },
+    });
+
+    const result = await executeJiraCreate({
+      summary: "Bug report",
+      description: "Something is broken",
+      project: "PROJ",
+      labels: ["bug", "urgent"],
+    });
+
+    expect(capturedFetchUrl).toBe("https://test.atlassian.net/rest/api/3/issue");
+    expect(capturedFetchInit?.method).toBe("POST");
+
+    // Check Basic auth header
+    const expectedAuth = Buffer.from("test@example.com:tok-123").toString("base64");
+    expect((capturedFetchInit?.headers as Record<string, string>)?.Authorization).toBe(
+      `Basic ${expectedAuth}`,
+    );
+
+    // Check body includes project, summary, labels
+    const body = JSON.parse(capturedFetchInit?.body as string);
+    expect(body.fields.project.key).toBe("PROJ");
+    expect(body.fields.summary).toBe("Bug report");
+    expect(body.fields.labels).toEqual(["bug", "urgent"]);
+
+    // Check description is ADF format
+    expect(body.fields.description.type).toBe("doc");
+    expect(body.fields.description.version).toBe(1);
+
+    // Check result
+    expect(result.key).toBe("PROJ-42");
+    expect(result.url).toBe("https://test.atlassian.net/browse/PROJ-42");
+  });
+
+  it("falls back to JIRA_DEFAULT_PROJECT when project not provided", async () => {
+    process.env.JIRA_BASE_URL = "https://test.atlassian.net";
+    process.env.JIRA_EMAIL = "test@example.com";
+    process.env.JIRA_API_TOKEN = "tok-123";
+    process.env.JIRA_DEFAULT_PROJECT = "DEFAULT";
+
+    installFetchMock({
+      status: 201,
+      body: { key: "DEFAULT-1", self: "..." },
+    });
+
+    await executeJiraCreate({
+      summary: "Test",
+      description: "Desc",
+    });
+
+    const body = JSON.parse(capturedFetchInit?.body as string);
+    expect(body.fields.project.key).toBe("DEFAULT");
+  });
+
+  it("throws on API error without exposing secrets", async () => {
+    process.env.JIRA_BASE_URL = "https://test.atlassian.net";
+    process.env.JIRA_EMAIL = "test@example.com";
+    process.env.JIRA_API_TOKEN = "tok-123";
+
+    installFetchMock({
+      status: 400,
+      body: { errorMessages: ["Project 'BAD' does not exist."], errors: {} },
+    });
+
+    try {
+      await executeJiraCreate({
+        summary: "Test",
+        description: "Desc",
+        project: "BAD",
+      });
+      expect(true).toBe(false); // should not reach here
+    } catch (err) {
+      const message = (err as Error).message;
+      expect(message).toContain("JIRA API error");
+      expect(message).toContain("does not exist");
+      // Must not contain secrets
+      expect(message).not.toContain("tok-123");
+      expect(message).not.toContain("test@example.com");
+    }
+  });
+
+  it("handles non-JSON error responses", async () => {
+    process.env.JIRA_BASE_URL = "https://test.atlassian.net";
+    process.env.JIRA_EMAIL = "test@example.com";
+    process.env.JIRA_API_TOKEN = "tok-123";
+
+    installFetchMockRaw({ status: 500, text: "Internal Server Error" });
+
+    await expect(
+      executeJiraCreate({ summary: "Test", description: "Desc", project: "PROJ" }),
+    ).rejects.toThrow("HTTP 500");
+  });
+
+  it("omits labels field when no labels provided", async () => {
+    process.env.JIRA_BASE_URL = "https://test.atlassian.net";
+    process.env.JIRA_EMAIL = "test@example.com";
+    process.env.JIRA_API_TOKEN = "tok-123";
+
+    installFetchMock({
+      status: 201,
+      body: { key: "PROJ-1", self: "..." },
+    });
+
+    await executeJiraCreate({
+      summary: "Test",
+      description: "Desc",
+      project: "PROJ",
+    });
+
+    const body = JSON.parse(capturedFetchInit?.body as string);
+    expect(body.fields.labels).toBeUndefined();
+  });
+
+  it("throws when only JIRA_BASE_URL is set (partial credentials)", async () => {
+    process.env.JIRA_BASE_URL = "https://test.atlassian.net";
+    delete process.env.JIRA_EMAIL;
+    delete process.env.JIRA_API_TOKEN;
+
+    await expect(
+      executeJiraCreate({
+        summary: "Test",
+        description: "Desc",
+        project: "PROJ",
+      }),
+    ).rejects.toThrow("Missing JIRA credentials");
+  });
+
+  it("throws when success response is not valid JSON", async () => {
+    process.env.JIRA_BASE_URL = "https://test.atlassian.net";
+    process.env.JIRA_EMAIL = "test@example.com";
+    process.env.JIRA_API_TOKEN = "tok-123";
+
+    // Return 201 but with invalid JSON body
+    globalThis.fetch = (async () => {
+      return new Response("not json", {
+        status: 201,
+        headers: { "Content-Type": "text/plain" },
+      });
+    }) as unknown as typeof globalThis.fetch;
+
+    await expect(
+      executeJiraCreate({ summary: "Test", description: "Desc", project: "PROJ" }),
+    ).rejects.toThrow("response could not be parsed");
+  });
+
+  it("throws when success response is missing key field", async () => {
+    process.env.JIRA_BASE_URL = "https://test.atlassian.net";
+    process.env.JIRA_EMAIL = "test@example.com";
+    process.env.JIRA_API_TOKEN = "tok-123";
+
+    installFetchMock({
+      status: 201,
+      body: { id: "12345", self: "https://test.atlassian.net/rest/api/3/issue/12345" },
+    });
+
+    await expect(
+      executeJiraCreate({ summary: "Test", description: "Desc", project: "PROJ" }),
+    ).rejects.toThrow("response could not be parsed");
+  });
+
+  it("strips trailing slash from base URL", async () => {
+    process.env.JIRA_BASE_URL = "https://test.atlassian.net/";
+    process.env.JIRA_EMAIL = "test@example.com";
+    process.env.JIRA_API_TOKEN = "tok-123";
+
+    installFetchMock({
+      status: 201,
+      body: { key: "PROJ-1", self: "..." },
+    });
+
+    const result = await executeJiraCreate({
+      summary: "Test",
+      description: "Desc",
+      project: "PROJ",
+    });
+
+    expect(capturedFetchUrl).toBe("https://test.atlassian.net/rest/api/3/issue");
+    expect(result.url).toBe("https://test.atlassian.net/browse/PROJ-1");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tool execute — integration with handleAction
+// ---------------------------------------------------------------------------
+
+describe("createJiraTicket — tool execute", () => {
+  it("calls handleAction with correct actionType and payload", async () => {
+    process.env.JIRA_DEFAULT_PROJECT = "FALLBACK";
+
+    const aiTool = createJiraTicket.tool as unknown as {
+      execute: (args: unknown, options: unknown) => Promise<unknown>;
+    };
+
+    await aiTool.execute(
+      { summary: "Test issue", description: "Details here" },
+      { toolCallId: "test-call", messages: [], abortSignal: undefined as unknown as AbortSignal },
+    );
+
+    expect(lastHandleActionCall).not.toBeNull();
+    const request = lastHandleActionCall!.request as Record<string, unknown>;
+    expect(request.actionType).toBe("jira:create");
+    expect(request.target).toBe("FALLBACK");
+    expect(request.reversible).toBe(true);
+    expect((request.payload as Record<string, unknown>).summary).toBe("Test issue");
+  });
+
+  it("uses explicit project when provided instead of JIRA_DEFAULT_PROJECT", async () => {
+    process.env.JIRA_DEFAULT_PROJECT = "FALLBACK";
+
+    const aiTool = createJiraTicket.tool as unknown as {
+      execute: (args: unknown, options: unknown) => Promise<unknown>;
+    };
+
+    await aiTool.execute(
+      { summary: "Explicit project", description: "Details", project: "EXPLICIT" },
+      { toolCallId: "test-call-2", messages: [], abortSignal: undefined as unknown as AbortSignal },
+    );
+
+    expect(lastHandleActionCall).not.toBeNull();
+    const request = lastHandleActionCall!.request as Record<string, unknown>;
+    expect(request.target).toBe("EXPLICIT");
+    expect((request.payload as Record<string, unknown>).project).toBe("EXPLICIT");
+  });
+});

package/templates/docker/src/lib/tools/actions/audit.ts

@@ -0,0 +1,47 @@
+/**
+ * Action lifecycle logger.
+ *
+ * Structured pino logs for every action state transition.
+ *
+ * State transitions:
+ * - pending -> approved -> executed | failed
+ * - pending -> denied
+ * - pending -> auto_approved (executed inline) | failed
+ * - pending -> timed_out (reserved, not yet implemented)
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+import type { ActionStatus } from "@atlas/api/lib/action-types";
+
+const log = createLogger("action-audit");
+
+export interface ActionAuditEntry {
+  actionId: string;
+  actionType: string;
+  status: ActionStatus;
+  latencyMs?: number;
+  userId?: string;
+  approverId?: string;
+  error?: string;
+}
+
+export function logActionAudit(entry: ActionAuditEntry): void {
+  const { actionId, actionType, status, latencyMs, userId, approverId, error } = entry;
+  const fields = {
+    actionId,
+    actionType,
+    status,
+    ...(latencyMs !== undefined && { latencyMs }),
+    ...(userId && { userId }),
+    ...(approverId && { approverId }),
+    ...(error && { error }),
+  };
+
+  if (status === "failed") {
+    log.error(fields, `action_${status}`);
+  } else if (status === "denied") {
+    log.warn(fields, `action_${status}`);
+  } else {
+    log.info(fields, `action_${status}`);
+  }
+}

package/templates/docker/src/lib/tools/actions/email.ts

@@ -0,0 +1,191 @@
+/**
+ * Email action — send reports via Resend.
+ *
+ * Exports:
+ * - executeEmailSend(params) — raw Resend SDK call
+ * - sendEmailReport — AtlasAction for the agent tool registry
+ */
+
+import { tool } from "ai";
+import { z } from "zod";
+import type { AtlasAction } from "@atlas/api/lib/action-types";
+import { buildActionRequest, handleAction } from "./handler";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("action:email");
+
+// ---------------------------------------------------------------------------
+// Domain allowlist validation
+// ---------------------------------------------------------------------------
+
+/** Extract the domain from an email address, handling display-name format. */
+function extractEmailDomain(addr: string): string | undefined {
+  // Handle display-name format: "User <user@company.com>"
+  const angleMatch = addr.match(/<([^>]+)>/);
+  const email = angleMatch ? angleMatch[1] : addr;
+  return email.split("@")[1]?.toLowerCase();
+}
+
+function validateAllowedDomains(
+  recipients: string[],
+): { valid: boolean; blocked: string[] } {
+  const raw = process.env.ATLAS_EMAIL_ALLOWED_DOMAINS;
+  if (!raw) return { valid: true, blocked: [] };
+
+  const allowed = raw
+    .split(",")
+    .map((d) => d.trim().toLowerCase())
+    .filter(Boolean);
+
+  if (allowed.length === 0) return { valid: true, blocked: [] };
+
+  const blocked: string[] = [];
+  for (const addr of recipients) {
+    const domain = extractEmailDomain(addr);
+    if (!domain || !allowed.includes(domain)) {
+      blocked.push(addr);
+    }
+  }
+
+  if (blocked.length > 0) {
+    log.warn({ blocked, allowed }, "Domain allowlist rejected recipients");
+  }
+
+  return { valid: blocked.length === 0, blocked };
+}
+
+// ---------------------------------------------------------------------------
+// Raw Resend API call
+// ---------------------------------------------------------------------------
+
+export interface EmailSendParams {
+  to: string | string[];
+  subject: string;
+  body: string;
+}
+
+export interface EmailSendResult {
+  id: string;
+}
+
+export async function executeEmailSend(
+  params: EmailSendParams,
+): Promise<EmailSendResult> {
+  const apiKey = process.env.RESEND_API_KEY;
+  if (!apiKey) {
+    log.error("Missing RESEND_API_KEY");
+    throw new Error("Missing RESEND_API_KEY. Set it to send emails via Resend.");
+  }
+
+  const fromAddress =
+    process.env.ATLAS_EMAIL_FROM ?? "Atlas <atlas@notifications.useatlas.dev>";
+  const recipients = Array.isArray(params.to) ? params.to : [params.to];
+
+  const response = await fetch("https://api.resend.com/emails", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      from: fromAddress,
+      to: recipients,
+      subject: params.subject,
+      html: params.body,
+    }),
+  });
+
+  if (!response.ok) {
+    let detail: string;
+    try {
+      const errorBody = (await response.json()) as { message?: string };
+      detail = errorBody.message ?? `HTTP ${response.status}`;
+    } catch {
+      try {
+        const text = await response.text();
+        detail = text ? `HTTP ${response.status}: ${text.slice(0, 200)}` : `HTTP ${response.status}`;
+      } catch {
+        detail = `HTTP ${response.status}`;
+      }
+    }
+    log.error({ status: response.status, detail }, "Resend API request failed");
+    throw new Error(`Resend API error: ${detail}`);
+  }
+
+  let data: { id?: string };
+  try {
+    data = (await response.json()) as { id?: string };
+  } catch (err) {
+    log.error({ err }, "Failed to parse Resend API success response");
+    throw new Error("Resend API returned unparseable response after success status", { cause: err });
+  }
+
+  if (!data.id) {
+    log.warn("Resend API returned success but no email ID — email may have been sent");
+  }
+  return { id: data.id ?? "unknown" };
+}
+
+// ---------------------------------------------------------------------------
+// Agent tool (AtlasAction)
+// ---------------------------------------------------------------------------
+
+const SEND_EMAIL_DESCRIPTION = `### Send Email Report
+Use sendEmailReport to email analysis results to stakeholders:
+- Provide recipient email addresses
+- Include a clear subject line
+- Format the body as HTML for rich formatting
+- Domain restrictions may apply (ATLAS_EMAIL_ALLOWED_DOMAINS)
+- Emails require admin approval before sending`;
+
+export const sendEmailReport: AtlasAction = {
+  name: "sendEmailReport",
+  description: SEND_EMAIL_DESCRIPTION,
+  actionType: "email:send",
+  reversible: false,
+  defaultApproval: "admin-only",
+  requiredCredentials: ["RESEND_API_KEY"],
+
+  tool: tool({
+    description:
+      "Send an email report. Requires admin approval before the email is sent.",
+    inputSchema: z.object({
+      to: z
+        .union([z.string(), z.array(z.string()).min(1)])
+        .describe("Recipient email address(es)"),
+      subject: z.string().describe("Email subject line"),
+      body: z.string().describe("Email body (HTML)"),
+    }),
+    execute: async ({ to, subject, body }) => {
+      const recipients = Array.isArray(to) ? to : [to];
+      log.info(
+        { to: recipients, subject },
+        "sendEmailReport invoked",
+      );
+
+      // Domain allowlist check — runs pre-approval
+      const domainCheck = validateAllowedDomains(recipients);
+      if (!domainCheck.valid) {
+        return {
+          status: "error" as const,
+          error: `Recipient domain not allowed: ${domainCheck.blocked.join(", ")}. Allowed domains: ${process.env.ATLAS_EMAIL_ALLOWED_DOMAINS}`,
+        };
+      }
+
+      const request = buildActionRequest({
+        actionType: "email:send",
+        target: recipients.join(", "),
+        summary: `Send email: "${subject}" to ${recipients.join(", ")}`,
+        payload: { to: recipients, subject, body },
+        reversible: false,
+      });
+
+      return handleAction(request, async (payload) => {
+        const result = await executeEmailSend(
+          payload as unknown as EmailSendParams,
+        );
+        return result;
+      });
+    },
+  }),
+};