@useatlas/create 0.0.1

package/templates/nextjs-standalone/src/lib/tools/actions/jira.ts

@@ -0,0 +1,220 @@
+/**
+ * JIRA action — create issues via JIRA REST API v3.
+ *
+ * Exports:
+ * - executeJiraCreate(params) — raw JIRA API call
+ * - createJiraTicket — 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:jira");
+
+// ---------------------------------------------------------------------------
+// ADF (Atlassian Document Format) helper
+// ---------------------------------------------------------------------------
+
+/** Convert plain text to a minimal ADF document (required by JIRA v3 API). */
+export function textToADF(text: string) {
+  const paragraphs = text
+    .split("\n\n")
+    .filter((p) => p.trim().length > 0);
+
+  // Fallback for completely empty or whitespace-only text
+  const segments = paragraphs.length > 0 ? paragraphs : ["(no description)"];
+
+  return {
+    version: 1,
+    type: "doc",
+    content: segments.map((paragraph) => ({
+      type: "paragraph",
+      content: [{ type: "text", text: paragraph }],
+    })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Raw JIRA API call
+// ---------------------------------------------------------------------------
+
+export interface JiraCreateParams {
+  summary: string;
+  description: string;
+  project?: string;
+  labels?: string[];
+}
+
+export interface JiraCreateResult {
+  key: string;
+  url: string;
+}
+
+export async function executeJiraCreate(
+  params: JiraCreateParams,
+): Promise<JiraCreateResult> {
+  const baseUrl = process.env.JIRA_BASE_URL;
+  const email = process.env.JIRA_EMAIL;
+  const apiToken = process.env.JIRA_API_TOKEN;
+
+  if (!baseUrl || !email || !apiToken) {
+    log.error("Missing JIRA credentials");
+    throw new Error(
+      "Missing JIRA credentials. Set JIRA_BASE_URL, JIRA_EMAIL, and JIRA_API_TOKEN.",
+    );
+  }
+
+  const project = params.project ?? process.env.JIRA_DEFAULT_PROJECT;
+  if (!project) {
+    log.error({ summary: params.summary }, "No JIRA project specified");
+    throw new Error(
+      "No JIRA project specified. Provide a project key or set JIRA_DEFAULT_PROJECT.",
+    );
+  }
+
+  const auth = Buffer.from(`${email}:${apiToken}`).toString("base64");
+  const url = `${baseUrl.replace(/\/$/, "")}/rest/api/3/issue`;
+
+  const body = {
+    fields: {
+      project: { key: project },
+      summary: params.summary,
+      description: textToADF(params.description),
+      issuetype: { name: "Task" },
+      ...(params.labels?.length ? { labels: params.labels } : {}),
+    },
+  };
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${auth}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    let detail: string;
+    try {
+      const errorBody = await response.json();
+      // JIRA returns { errorMessages, errors } — extract actionable info without exposing internals
+      const messages = (errorBody as { errorMessages?: string[] }).errorMessages ?? [];
+      const fieldErrors = Object.entries(
+        (errorBody as { errors?: Record<string, string> }).errors ?? {},
+      ).map(([field, msg]) => `${field}: ${msg}`);
+      detail = [...messages, ...fieldErrors].join("; ") || `HTTP ${response.status}`;
+    } catch {
+      // JSON parsing failed — try to get raw text for diagnostics
+      let rawText = "";
+      try {
+        rawText = await response.text();
+      } catch {
+        // ignore — body may already be consumed
+      }
+      detail = rawText
+        ? `HTTP ${response.status}: ${rawText.slice(0, 200)}`
+        : `HTTP ${response.status}`;
+    }
+    log.error({ status: response.status, url, detail, project }, "JIRA API request failed");
+    throw new Error(`JIRA API error: ${detail}`);
+  }
+
+  let data: { key: string; self: string };
+  try {
+    data = (await response.json()) as { key: string; self: string };
+  } catch (err) {
+    log.error({ err }, "Failed to parse JIRA success response");
+    throw new Error(
+      "JIRA issue may have been created but response could not be parsed",
+      { cause: err },
+    );
+  }
+
+  if (!data.key) {
+    log.error({ data }, "JIRA response missing issue key");
+    throw new Error(
+      "JIRA issue may have been created but response could not be parsed",
+    );
+  }
+
+  return {
+    key: data.key,
+    url: `${baseUrl.replace(/\/$/, "")}/browse/${data.key}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Agent tool (AtlasAction)
+// ---------------------------------------------------------------------------
+
+const CREATE_JIRA_DESCRIPTION = `### Create JIRA Ticket
+Use createJiraTicket to create a new JIRA issue based on the analysis findings:
+- Provide a clear, concise summary (max 255 chars)
+- Include relevant details in the description
+- Optionally specify a project key and labels
+- The ticket will require approval before creation`;
+
+export const createJiraTicket: AtlasAction = {
+  name: "createJiraTicket",
+  description: CREATE_JIRA_DESCRIPTION,
+  actionType: "jira:create",
+  reversible: true,
+  defaultApproval: "manual",
+  requiredCredentials: ["JIRA_BASE_URL", "JIRA_EMAIL", "JIRA_API_TOKEN"],
+
+  tool: tool({
+    description:
+      "Create a JIRA issue. Requires approval before the issue is actually created.",
+    inputSchema: z.object({
+      summary: z
+        .string()
+        .max(255)
+        .describe("Issue summary / title (max 255 characters)"),
+      description: z
+        .string()
+        .describe("Detailed issue description"),
+      project: z
+        .string()
+        .optional()
+        .describe(
+          "JIRA project key (e.g. 'PROJ'). Falls back to JIRA_DEFAULT_PROJECT env.",
+        ),
+      labels: z
+        .array(z.string())
+        .optional()
+        .describe("Optional labels to apply to the issue"),
+    }),
+    execute: async ({ summary, description, project, labels }) => {
+      log.info({ summary, project }, "createJiraTicket invoked");
+
+      const request = buildActionRequest({
+        actionType: "jira:create",
+        target: project ?? process.env.JIRA_DEFAULT_PROJECT ?? "unknown",
+        summary: `Create JIRA ticket: ${summary}`,
+        payload: { summary, description, project, labels },
+        reversible: true,
+      });
+
+      return handleAction(request, async (payload) => {
+        const result = await executeJiraCreate(
+          payload as unknown as JiraCreateParams,
+        );
+        return {
+          ...result,
+          // Best-effort rollback metadata — transitioning to "Closed" depends on
+          // the JIRA workflow configuration and is NOT guaranteed to work in all
+          // JIRA instances or project configurations.
+          rollbackInfo: {
+            method: "transition",
+            params: { issueKey: result.key, targetStatus: "Closed" },
+          },
+        };
+      });
+    },
+  }),
+};

package/templates/nextjs-standalone/src/lib/tools/explore-nsjail.ts

@@ -0,0 +1,343 @@
+/**
+ * nsjail backend for the explore tool.
+ *
+ * Uses nsjail (Linux namespaces) to run shell commands in a
+ * sandboxed process. Only loaded when nsjail is available on PATH,
+ * ATLAS_NSJAIL_PATH is set, or ATLAS_SANDBOX=nsjail is configured.
+ *
+ * Security: the jail runs with no network (default in nsjail), read-only
+ * bind-mount of semantic/, writable tmpfs for scratch, and no access
+ * to .env or any host secrets. Process runs as nobody (65534:65534).
+ */
+
+import type { ExploreBackend, ExecResult } from "./explore";
+import * as fs from "fs";
+
+/** Maximum bytes to read from stdout/stderr (1 MB). */
+const MAX_OUTPUT = 1024 * 1024;
+
+/** Read up to `max` bytes from a stream, releasing the reader on completion or error. */
+async function readLimited(
+  stream: ReadableStream,
+  max: number,
+): Promise<string> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > max) {
+        chunks.push(value.slice(0, max - (total - value.byteLength)));
+        break;
+      }
+      chunks.push(value);
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+  return new TextDecoder().decode(Buffer.concat(chunks));
+}
+
+/** Parse a positive integer from an env var, returning defaultValue on invalid input. */
+function parsePositiveInt(
+  envVar: string,
+  defaultValue: number,
+  name: string,
+): number {
+  const raw = process.env[envVar];
+  if (raw === undefined) return defaultValue;
+  const parsed = parseInt(raw, 10);
+  if (isNaN(parsed) || parsed <= 0) {
+    console.warn(
+      `[atlas] Invalid ${envVar}="${raw}" for ${name}, using default: ${defaultValue}`,
+    );
+    return defaultValue;
+  }
+  return parsed;
+}
+
+/** Resolve the nsjail binary path, or null if unavailable. */
+export function findNsjailBinary(): string | null {
+  // 1. Explicit path from env
+  const explicit = process.env.ATLAS_NSJAIL_PATH;
+  if (explicit) {
+    try {
+      fs.accessSync(explicit, fs.constants.X_OK);
+      return explicit;
+    } catch (err) {
+      const code =
+        err instanceof Error && "code" in err
+          ? (err as NodeJS.ErrnoException).code
+          : "unknown";
+      console.error(
+        `[atlas] ATLAS_NSJAIL_PATH="${explicit}" is not executable (${code})`,
+      );
+      return null;
+    }
+  }
+
+  // 2. Search PATH
+  const pathDirs = (process.env.PATH ?? "").split(":");
+  for (const dir of pathDirs) {
+    const candidate = `${dir}/nsjail`;
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+/** Check whether nsjail is available on this system. */
+export function isNsjailAvailable(): boolean {
+  return findNsjailBinary() !== null;
+}
+
+/**
+ * Run a minimal nsjail command to verify namespace support actually works.
+ *
+ * Exercises the exact same namespace config (user, PID, mount, network)
+ * that real explore commands use. Returns `{ ok: true }` if nsjail can
+ * create namespaces on this platform, or `{ ok: false, error }` with
+ * a diagnostic message otherwise.
+ */
+export async function testNsjailCapabilities(
+  nsjailPath: string,
+  semanticRoot: string,
+): Promise<{ ok: boolean; error?: string }> {
+  const TIMEOUT_MS = 5000;
+  try {
+    const args = buildNsjailArgs(nsjailPath, semanticRoot, "echo nsjail-ok");
+    const proc = Bun.spawn(args, {
+      env: JAIL_ENV,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const timer = setTimeout(() => proc.kill(), TIMEOUT_MS);
+    try {
+      const [stdout, stderr] = await Promise.all([
+        readLimited(proc.stdout, MAX_OUTPUT),
+        readLimited(proc.stderr, MAX_OUTPUT),
+      ]);
+      const exitCode = await proc.exited;
+      clearTimeout(timer);
+
+      if (exitCode === 0 && stdout.includes("nsjail-ok")) {
+        return { ok: true };
+      }
+
+      return {
+        ok: false,
+        error: `nsjail exited with code ${exitCode}${stderr ? `: ${stderr.trim()}` : ""}`,
+      };
+    } catch (err) {
+      clearTimeout(timer);
+      throw err;
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/** Build the nsjail CLI args for a single command execution. */
+function buildNsjailArgs(
+  nsjailPath: string,
+  semanticRoot: string,
+  command: string,
+): string[] {
+  const timeLimit = parsePositiveInt(
+    "ATLAS_NSJAIL_TIME_LIMIT",
+    10,
+    "time limit",
+  );
+  const memoryLimit = parsePositiveInt(
+    "ATLAS_NSJAIL_MEMORY_LIMIT",
+    256,
+    "memory limit",
+  );
+
+  return [
+    nsjailPath,
+    "--mode",
+    "o",
+
+    // Read-only bind mounts
+    "-R",
+    `${semanticRoot}:/semantic`,
+    "-R",
+    "/bin",
+    "-R",
+    "/usr/bin",
+    "-R",
+    "/lib",
+    "-R",
+    "/lib64",
+    "-R",
+    "/usr/lib",
+
+    // Minimal /dev
+    "-R",
+    "/dev/null",
+    "-R",
+    "/dev/zero",
+    "-R",
+    "/dev/urandom",
+
+    // /proc for correct namespace operation
+    "--proc_path",
+    "/proc",
+
+    // Writable tmpfs for scratch
+    "-T",
+    "/tmp",
+
+    // Working directory
+    "--cwd",
+    "/semantic",
+
+    // Network namespace is enabled by default in nsjail (no network access).
+    // Older versions used --clone_newnet to opt in; current versions use
+    // --disable_clone_newnet to opt out. No flag needed.
+
+    // Time limit
+    "-t",
+    String(timeLimit),
+
+    // Resource limits
+    "--rlimit_as",
+    String(memoryLimit),
+    "--rlimit_fsize",
+    "10",
+    "--rlimit_nproc",
+    "5",
+    "--rlimit_nofile",
+    "64",
+
+    // Run as nobody
+    "-u",
+    "65534",
+    "-g",
+    "65534",
+
+    // Suppress nsjail info logs but keep error diagnostics
+    "--quiet",
+
+    // Command to execute
+    "--",
+    "/bin/bash",
+    "-c",
+    command,
+  ];
+}
+
+/** Minimal env passed into the jail — no secrets. */
+const JAIL_ENV: Record<string, string> = {
+  PATH: "/bin:/usr/bin",
+  HOME: "/tmp",
+  LANG: "C.UTF-8",
+};
+
+/** Callbacks injected by the explore module to avoid circular dynamic imports. */
+export interface NsjailCallbacks {
+  onInfrastructureError: () => void;
+  onNsjailFailed: () => void;
+}
+
+export async function createNsjailBackend(
+  semanticRoot: string,
+  callbacks: NsjailCallbacks,
+): Promise<ExploreBackend> {
+  // Validate nsjail binary
+  const nsjailPath = findNsjailBinary();
+  if (!nsjailPath) {
+    throw new Error(
+      "nsjail binary not found. Install nsjail or set ATLAS_NSJAIL_PATH. " +
+        "In non-production environments, the system will fall back to just-bash.",
+    );
+  }
+
+  // Validate semantic root exists
+  try {
+    fs.accessSync(semanticRoot, fs.constants.R_OK);
+  } catch (err) {
+    const code =
+      err instanceof Error && "code" in err
+        ? (err as NodeJS.ErrnoException).code
+        : "unknown";
+    throw new Error(
+      `Semantic layer directory not readable: ${semanticRoot} (${code}). ` +
+        "Run 'bun run atlas -- init' to generate a semantic layer.",
+      { cause: err },
+    );
+  }
+
+  return {
+    exec: async (command: string): Promise<ExecResult> => {
+      let proc;
+      try {
+        const args = buildNsjailArgs(nsjailPath, semanticRoot, command);
+        proc = Bun.spawn(args, {
+          env: JAIL_ENV,
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+      } catch (err) {
+        // Spawn itself failed — infrastructure error
+        const detail = err instanceof Error ? err.message : String(err);
+        console.error("[atlas] nsjail spawn failed:", detail);
+        callbacks.onInfrastructureError();
+        throw new Error(
+          `nsjail infrastructure error: ${detail}. Backend cache cleared; nsjail will be re-initialized on next explore call.`,
+          { cause: err },
+        );
+      }
+
+      let stdout: string, stderr: string, exitCode: number;
+      try {
+        [stdout, stderr] = await Promise.all([
+          readLimited(proc.stdout, MAX_OUTPUT),
+          readLimited(proc.stderr, MAX_OUTPUT),
+        ]);
+        exitCode = await proc.exited;
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        console.error(
+          `[atlas] nsjail process I/O error: ${detail} | command: ${command}`,
+        );
+        throw new Error(
+          `nsjail process I/O error: ${detail}`,
+          { cause: err },
+        );
+      }
+
+      // Interpret nsjail-specific exit codes
+      if (exitCode === 109) {
+        console.error(
+          "[atlas] nsjail setup failure (exit 109) — sandbox may not have been applied. stderr:",
+          stderr,
+        );
+        // Mark nsjail as permanently failed so the system falls back to just-bash
+        // (when ATLAS_SANDBOX=nsjail, getExploreBackend will still throw hard)
+        callbacks.onNsjailFailed();
+      }
+      if (exitCode > 128) {
+        const signal = exitCode - 128;
+        console.warn(
+          `[atlas] nsjail child killed by signal ${signal} | command: ${command}`,
+        );
+      }
+
+      return { stdout, stderr, exitCode };
+    },
+  };
+}