@useatlas/create 0.0.1

package/templates/docker/src/lib/conversation-types.ts

@@ -0,0 +1,29 @@
+/**
+ * Conversation persistence types for Atlas.
+ */
+
+export type MessageRole = "user" | "assistant" | "system" | "tool";
+export type Surface = "web" | "api" | "mcp" | "slack";
+
+export interface Conversation {
+  id: string;
+  userId: string | null;
+  title: string | null;
+  surface: Surface;
+  connectionId: string | null;
+  starred: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Message {
+  id: string;
+  conversationId: string;
+  role: MessageRole;
+  content: unknown;
+  createdAt: string;
+}
+
+export interface ConversationWithMessages extends Conversation {
+  messages: Message[];
+}

package/templates/docker/src/lib/conversations.ts

@@ -0,0 +1,270 @@
+/**
+ * Conversation persistence — CRUD operations for conversations and messages.
+ *
+ * Functions that need callers to distinguish failure modes (get, delete, star)
+ * return discriminated union results (CrudResult / CrudDataResult). Functions
+ * that are fire-and-forget (createConversation, addMessage) still return
+ * null/void. Failures are logged but never propagate as exceptions.
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+import {
+  hasInternalDB,
+  internalQuery,
+  internalExecute,
+} from "@atlas/api/lib/db/internal";
+
+const log = createLogger("conversations");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+import type { MessageRole, Surface, Conversation, Message, ConversationWithMessages } from "@atlas/api/lib/conversation-types";
+export type { MessageRole, Surface, Conversation, Message, ConversationWithMessages };
+
+/** Failure reason for CRUD operations that need to distinguish no-DB / not-found / error. */
+export type CrudFailReason = "no_db" | "not_found" | "error";
+
+/** Discriminated union result for mutation CRUD ops (star, delete). */
+export type CrudResult = { ok: true } | { ok: false; reason: CrudFailReason };
+
+/** Discriminated union result for CRUD ops that return data on success. */
+export type CrudDataResult<T> = { ok: true; data: T } | { ok: false; reason: CrudFailReason };
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rowToConversation(r: Record<string, unknown>): Conversation {
+  return {
+    id: r.id as string,
+    userId: (r.user_id as string) ?? null,
+    title: (r.title as string) ?? null,
+    surface: (r.surface as Surface) ?? "web",
+    connectionId: (r.connection_id as string) ?? null,
+    starred: r.starred === true,
+    createdAt: String(r.created_at),
+    updatedAt: String(r.updated_at),
+  };
+}
+
+/** Generate a short title from the first user question. */
+export function generateTitle(question: string): string {
+  const cleaned = question.replace(/[\r\n]+/g, " ").trim();
+  if (!cleaned) return "New conversation";
+  if (cleaned.length <= 80) return cleaned;
+  return cleaned.slice(0, 77) + "...";
+}
+
+// ---------------------------------------------------------------------------
+// CRUD
+// ---------------------------------------------------------------------------
+
+/** Create a new conversation. Returns { id } or null if unavailable. */
+export async function createConversation(opts: {
+  id?: string;
+  userId?: string | null;
+  title?: string | null;
+  surface?: string;
+  connectionId?: string | null;
+}): Promise<{ id: string } | null> {
+  if (!hasInternalDB()) return null;
+  try {
+    const rows = opts.id
+      ? await internalQuery<{ id: string }>(
+          `INSERT INTO conversations (id, user_id, title, surface, connection_id)
+           VALUES ($1, $2, $3, $4, $5)
+           RETURNING id`,
+          [
+            opts.id,
+            opts.userId ?? null,
+            opts.title ?? null,
+            opts.surface ?? "web",
+            opts.connectionId ?? null,
+          ],
+        )
+      : await internalQuery<{ id: string }>(
+          `INSERT INTO conversations (user_id, title, surface, connection_id)
+           VALUES ($1, $2, $3, $4)
+           RETURNING id`,
+          [
+            opts.userId ?? null,
+            opts.title ?? null,
+            opts.surface ?? "web",
+            opts.connectionId ?? null,
+          ],
+        );
+    return rows[0] ?? null;
+  } catch (err) {
+    log.error({ err: err instanceof Error ? err.message : String(err) }, "createConversation failed");
+    return null;
+  }
+}
+
+/** Fire-and-forget — inserts the message and bumps updated_at in two separate non-transactional writes. */
+export function addMessage(opts: {
+  conversationId: string;
+  role: MessageRole;
+  content: unknown;
+}): void {
+  if (!hasInternalDB()) return;
+  // internalExecute is fire-and-forget — async errors are logged internally.
+  // Two separate non-transactional writes (partial success is possible).
+  internalExecute(
+    `INSERT INTO messages (conversation_id, role, content) VALUES ($1, $2, $3)`,
+    [opts.conversationId, opts.role, JSON.stringify(opts.content)],
+  );
+  internalExecute(
+    `UPDATE conversations SET updated_at = now() WHERE id = $1`,
+    [opts.conversationId],
+  );
+}
+
+/** Fetches a conversation with its messages. When userId is provided, enforces ownership (AND user_id = $2); when omitted, fetches without ownership check. */
+export async function getConversation(
+  id: string,
+  userId?: string | null,
+): Promise<CrudDataResult<ConversationWithMessages>> {
+  if (!hasInternalDB()) return { ok: false, reason: "no_db" };
+  try {
+    const convRows = userId
+      ? await internalQuery<Record<string, unknown>>(
+          `SELECT id, user_id, title, surface, connection_id, starred, created_at, updated_at
+           FROM conversations WHERE id = $1 AND user_id = $2`,
+          [id, userId],
+        )
+      : await internalQuery<Record<string, unknown>>(
+          `SELECT id, user_id, title, surface, connection_id, starred, created_at, updated_at
+           FROM conversations WHERE id = $1`,
+          [id],
+        );
+
+    if (convRows.length === 0) return { ok: false, reason: "not_found" };
+
+    const msgRows = await internalQuery<Record<string, unknown>>(
+      `SELECT id, conversation_id, role, content, created_at
+       FROM messages WHERE conversation_id = $1 ORDER BY created_at ASC`,
+      [id],
+    );
+
+    return {
+      ok: true,
+      data: {
+        ...rowToConversation(convRows[0]),
+        messages: msgRows.map((m) => ({
+          id: m.id as string,
+          conversationId: m.conversation_id as string,
+          role: m.role as MessageRole,
+          content: m.content,
+          createdAt: String(m.created_at),
+        })),
+      },
+    };
+  } catch (err) {
+    log.error({ err: err instanceof Error ? err.message : String(err) }, "getConversation failed");
+    return { ok: false, reason: "error" };
+  }
+}
+
+/** List conversations (metadata only, no messages). Auth-scoped when userId is provided. */
+export async function listConversations(opts?: {
+  userId?: string | null;
+  starred?: boolean;
+  limit?: number;
+  offset?: number;
+}): Promise<{ conversations: Conversation[]; total: number }> {
+  const empty = { conversations: [], total: 0 };
+  if (!hasInternalDB()) return empty;
+
+  const limit = opts?.limit ?? 20;
+  const offset = opts?.offset ?? 0;
+
+  try {
+    // Build WHERE clause dynamically
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+    let paramIdx = 1;
+
+    if (opts?.userId) {
+      conditions.push(`user_id = $${paramIdx++}`);
+      params.push(opts.userId);
+    }
+    if (opts?.starred !== undefined) {
+      conditions.push(`starred = $${paramIdx++}`);
+      params.push(opts.starred);
+    }
+
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+
+    const countRows = await internalQuery<Record<string, unknown>>(
+      `SELECT COUNT(*)::int AS total FROM conversations ${where}`,
+      params,
+    );
+    const dataRows = await internalQuery<Record<string, unknown>>(
+      `SELECT id, user_id, title, surface, connection_id, starred, created_at, updated_at
+       FROM conversations ${where}
+       ORDER BY updated_at DESC LIMIT $${paramIdx++} OFFSET $${paramIdx++}`,
+      [...params, limit, offset],
+    );
+
+    const total = (countRows[0]?.total as number) ?? 0;
+
+    return {
+      conversations: dataRows.map(rowToConversation),
+      total,
+    };
+  } catch (err) {
+    log.error({ err: err instanceof Error ? err.message : String(err) }, "listConversations failed");
+    return empty;
+  }
+}
+
+/** Set the starred flag on a conversation. Auth-scoped when userId is provided. */
+export async function starConversation(
+  id: string,
+  starred: boolean,
+  userId?: string | null,
+): Promise<CrudResult> {
+  if (!hasInternalDB()) return { ok: false, reason: "no_db" };
+  try {
+    const rows = userId
+      ? await internalQuery<{ id: string }>(
+          `UPDATE conversations SET starred = $1, updated_at = now()
+           WHERE id = $2 AND user_id = $3 RETURNING id`,
+          [starred, id, userId],
+        )
+      : await internalQuery<{ id: string }>(
+          `UPDATE conversations SET starred = $1, updated_at = now()
+           WHERE id = $2 RETURNING id`,
+          [starred, id],
+        );
+    return rows.length > 0 ? { ok: true } : { ok: false, reason: "not_found" };
+  } catch (err) {
+    log.error({ err: err instanceof Error ? err.message : String(err) }, "starConversation failed");
+    return { ok: false, reason: "error" };
+  }
+}
+
+/** Delete a conversation (CASCADE deletes messages). Auth-scoped when userId is provided. */
+export async function deleteConversation(
+  id: string,
+  userId?: string | null,
+): Promise<CrudResult> {
+  if (!hasInternalDB()) return { ok: false, reason: "no_db" };
+  try {
+    const rows = userId
+      ? await internalQuery<{ id: string }>(
+          `DELETE FROM conversations WHERE id = $1 AND user_id = $2 RETURNING id`,
+          [id, userId],
+        )
+      : await internalQuery<{ id: string }>(
+          `DELETE FROM conversations WHERE id = $1 RETURNING id`,
+          [id],
+        );
+    return rows.length > 0 ? { ok: true } : { ok: false, reason: "not_found" };
+  } catch (err) {
+    log.error({ err: err instanceof Error ? err.message : String(err) }, "deleteConversation failed");
+    return { ok: false, reason: "error" };
+  }
+}

package/templates/docker/src/lib/db/__tests__/connection.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Tests for detectDBType from connection.ts.
+ *
+ * sql.test.ts registers a global mock.module for @/lib/db/connection which
+ * persists across bun's test runner. To test the real implementation, we
+ * import the source file via a cache-busting query string that bypasses the mock.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { resolve } from "path";
+
+const modulePath = resolve(__dirname, "../connection.ts");
+const mod = await import(`${modulePath}?t=${Date.now()}`);
+const detectDBType = mod.detectDBType as (url?: string) => "postgres" | "mysql" | "duckdb";
+
+describe("detectDBType", () => {
+  const origDatabaseUrl = process.env.ATLAS_DATASOURCE_URL;
+
+  beforeEach(() => {
+    if (origDatabaseUrl !== undefined) {
+      process.env.ATLAS_DATASOURCE_URL = origDatabaseUrl;
+    } else {
+      delete process.env.ATLAS_DATASOURCE_URL;
+    }
+  });
+
+  it("detects postgresql:// as postgres", () => {
+    expect(detectDBType("postgresql://user:pass@localhost:5432/db")).toBe("postgres");
+  });
+
+  it("detects postgres:// as postgres", () => {
+    expect(detectDBType("postgres://user:pass@localhost:5432/db")).toBe("postgres");
+  });
+
+  it("detects mysql:// as mysql", () => {
+    expect(detectDBType("mysql://user:pass@localhost:3306/db")).toBe("mysql");
+  });
+
+  it("detects mysql2:// as mysql", () => {
+    expect(detectDBType("mysql2://user:pass@localhost:3306/db")).toBe("mysql");
+  });
+
+  it("uses ATLAS_DATASOURCE_URL env var when no argument provided", () => {
+    process.env.ATLAS_DATASOURCE_URL = "mysql://test@localhost/db";
+    expect(detectDBType()).toBe("mysql");
+  });
+
+  it("throws when ATLAS_DATASOURCE_URL is unset and no argument provided", () => {
+    delete process.env.ATLAS_DATASOURCE_URL;
+    expect(() => detectDBType()).toThrow("No database URL provided");
+  });
+
+  it("throws for empty string argument", () => {
+    expect(() => detectDBType("")).toThrow("No database URL provided");
+  });
+
+  it("detects duckdb:// as duckdb", () => {
+    expect(detectDBType("duckdb://:memory:")).toBe("duckdb");
+  });
+
+  it("detects duckdb://path as duckdb", () => {
+    expect(detectDBType("duckdb:///tmp/test.duckdb")).toBe("duckdb");
+  });
+
+  it("unrecognized URL throws an error", () => {
+    expect(() => detectDBType("file:./data/test.db")).toThrow(
+      "Unsupported database URL"
+    );
+  });
+});

package/templates/docker/src/lib/db/__tests__/duckdb.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Tests for the DuckDB adapter (duckdb.ts) and DuckDB URL parsing.
+ *
+ * Uses a real in-memory DuckDB instance (no mocks) to verify end-to-end
+ * query execution, column extraction, and close behavior.
+ */
+import { describe, it, expect, afterEach } from "bun:test";
+import { parseDuckDBUrl, createDuckDBConnection } from "../duckdb";
+import type { DBConnection } from "../connection";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+describe("parseDuckDBUrl", () => {
+  it("parses duckdb://:memory: as in-memory", () => {
+    const config = parseDuckDBUrl("duckdb://:memory:");
+    expect(config.path).toBe(":memory:");
+  });
+
+  it("parses bare duckdb:// as in-memory", () => {
+    const config = parseDuckDBUrl("duckdb://");
+    expect(config.path).toBe(":memory:");
+  });
+
+  it("parses duckdb:///absolute/path.duckdb", () => {
+    const config = parseDuckDBUrl("duckdb:///tmp/test.duckdb");
+    expect(config.path).toBe("/tmp/test.duckdb");
+  });
+
+  it("parses duckdb://relative/path.duckdb", () => {
+    const config = parseDuckDBUrl("duckdb://data/test.duckdb");
+    expect(config.path).toBe("data/test.duckdb");
+  });
+
+  it("throws for non-duckdb:// URL", () => {
+    expect(() => parseDuckDBUrl("postgresql://localhost/db")).toThrow("Invalid DuckDB URL");
+  });
+});
+
+describe("createDuckDBConnection", () => {
+  let conn: DBConnection | null = null;
+
+  afterEach(async () => {
+    if (conn) {
+      await conn.close();
+      conn = null;
+    }
+  });
+
+  it("creates a connection and runs a simple query", async () => {
+    conn = createDuckDBConnection({ path: ":memory:", readOnly: false });
+    const result = await conn.query("SELECT 42 AS answer");
+    expect(result.columns).toEqual(["answer"]);
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0].answer).toBe(42);
+  });
+
+  it("returns correct columns and rows for multi-column queries", async () => {
+    conn = createDuckDBConnection({ path: ":memory:", readOnly: false });
+    const result = await conn.query("SELECT 1 AS a, 'hello' AS b, true AS c");
+    expect(result.columns).toEqual(["a", "b", "c"]);
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0].a).toBe(1);
+    expect(result.rows[0].b).toBe("hello");
+    expect(result.rows[0].c).toBe(true);
+  });
+
+  it("handles empty result sets", async () => {
+    conn = createDuckDBConnection({ path: ":memory:", readOnly: false });
+    const result = await conn.query("SELECT 1 AS n WHERE false");
+    expect(result.columns).toEqual(["n"]);
+    expect(result.rows).toHaveLength(0);
+  });
+
+  it("supports CREATE TABLE and SELECT in read-write mode", async () => {
+    conn = createDuckDBConnection({ path: ":memory:", readOnly: false });
+    await conn.query("CREATE TABLE test (id INTEGER, name VARCHAR)");
+    await conn.query("INSERT INTO test VALUES (1, 'alice'), (2, 'bob')");
+    const result = await conn.query("SELECT * FROM test ORDER BY id");
+    expect(result.columns).toEqual(["id", "name"]);
+    expect(result.rows).toHaveLength(2);
+    expect(result.rows[0].name).toBe("alice");
+    expect(result.rows[1].name).toBe("bob");
+  });
+
+  it("supports VALUES clause for inline data", async () => {
+    conn = createDuckDBConnection({ path: ":memory:", readOnly: false });
+    const result = await conn.query(
+      "SELECT * FROM (VALUES (1, 'a'), (2, 'b'), (3, 'c')) AS t(id, letter)"
+    );
+    expect(result.rows).toHaveLength(3);
+  });
+
+  it("close is idempotent", async () => {
+    conn = createDuckDBConnection({ path: ":memory:", readOnly: false });
+    await conn.query("SELECT 1");
+    await conn.close();
+    await conn.close(); // Should not throw
+    conn = null; // Prevent afterEach from closing again
+  });
+
+  it("enforces read-only mode for file-based databases", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "atlas-duckdb-ro-"));
+    try {
+      const dbPath = path.join(tmpDir, "test.duckdb");
+
+      // Create and populate the database first (read-write)
+      const rwConn = createDuckDBConnection({ path: dbPath, readOnly: false });
+      await rwConn.query("CREATE TABLE test (id INTEGER)");
+      await rwConn.query("INSERT INTO test VALUES (1)");
+      await rwConn.close();
+
+      // Open in read-only mode (default for file-based)
+      conn = createDuckDBConnection({ path: dbPath });
+      const result = await conn.query("SELECT * FROM test");
+      expect(result.rows).toHaveLength(1);
+
+      // Write operations should fail
+      expect(conn.query("INSERT INTO test VALUES (2)")).rejects.toThrow();
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("respects timeoutMs parameter", async () => {
+    conn = createDuckDBConnection({ path: ":memory:", readOnly: false });
+    // A very short timeout on a query that takes some time
+    await expect(
+      conn.query("SELECT COUNT(*) FROM generate_series(1, 100000000)", 1)
+    ).rejects.toThrow("timed out");
+  });
+
+  it("can recover after close by re-initializing", async () => {
+    conn = createDuckDBConnection({ path: ":memory:", readOnly: false });
+    await conn.query("SELECT 1");
+    await conn.close();
+    // After close + retry, lazy init should re-create the connection
+    const result = await conn.query("SELECT 42 AS answer");
+    expect(result.rows[0].answer).toBe(42);
+  });
+});