@useatlas/create 0.0.5 → 0.0.7

package/templates/nextjs-standalone/src/api/routes/discord.ts

@@ -0,0 +1,274 @@
+/**
+ * Discord integration OAuth routes.
+ *
+ * - GET /api/v1/discord/install   — Redirect to Discord OAuth2 authorize
+ * - GET /api/v1/discord/callback  — Handle OAuth2 authorization callback
+ *
+ * Discord uses OAuth2 to authorize a bot into a guild (server).
+ * Platform operator registers a Discord Application and sets
+ * DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET as env vars.
+ * What changes per-org is the guild authorization — like Teams,
+ * the bot token itself is a platform-level credential.
+ */
+
+import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { z } from "zod";
+import { createLogger } from "@atlas/api/lib/logger";
+import { saveDiscordInstallation } from "@atlas/api/lib/discord/store";
+import { saveOAuthState, consumeOAuthState } from "@atlas/api/lib/auth/oauth-state";
+import { ErrorSchema } from "./shared-schemas";
+import { validationHook } from "./validation-hook";
+
+const log = createLogger("discord");
+
+const discord = new OpenAPIHono({ defaultHook: validationHook });
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+const installRoute = createRoute({
+  method: "get",
+  path: "/install",
+  tags: ["Discord"],
+  summary: "Discord OAuth install redirect",
+  description:
+    "Redirects to the Discord OAuth2 authorize page. Requires DISCORD_CLIENT_ID to be configured.",
+  responses: {
+    302: {
+      description: "Redirect to Discord OAuth2 authorize page",
+    },
+    501: {
+      description: "Discord not configured",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const callbackRoute = createRoute({
+  method: "get",
+  path: "/callback",
+  tags: ["Discord"],
+  summary: "Discord OAuth callback",
+  description:
+    "Handles the OAuth2 callback from Discord. Verifies the guild authorization, " +
+    "saves the installation, and returns HTML on success or failure.",
+  request: {
+    query: z.object({
+      state: z.string().optional().openapi({ description: "CSRF state parameter" }),
+      code: z.string().optional().openapi({ description: "Authorization code from Discord" }),
+      guild_id: z.string().optional().openapi({ description: "Authorized guild ID" }),
+      error: z.string().optional().openapi({ description: "Error code from Discord on denial" }),
+      error_description: z.string().optional().openapi({ description: "Human-readable error from Discord" }),
+    }),
+  },
+  responses: {
+    200: {
+      description: "Installation successful (HTML response)",
+      content: { "text/html": { schema: z.string() } },
+    },
+    400: {
+      description: "Invalid or expired state, or authorization denied",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    500: {
+      description: "Installation failed (HTML response)",
+      content: { "text/html": { schema: z.string() } },
+    },
+    501: {
+      description: "Discord not configured",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+// --- GET /api/v1/discord/install ---
+
+discord.openapi(installRoute, async (c) => {
+  const clientId = process.env.DISCORD_CLIENT_ID;
+  if (!clientId) {
+    return c.json({ error: "discord_not_configured", message: "Discord not configured" }, 501);
+  }
+
+  // Extract orgId from session if available (admin clicking "Connect to Discord")
+  let orgId: string | undefined;
+  try {
+    const authResult = c.get("authResult" as never) as
+      | { user?: { activeOrganizationId?: string } }
+      | undefined;
+    orgId = authResult?.user?.activeOrganizationId ?? undefined;
+  } catch (err) {
+    log.debug(
+      { err: err instanceof Error ? err.message : String(err) },
+      "authResult not available on Discord install route",
+    );
+  }
+
+  const nonce = crypto.randomUUID();
+  try {
+    await saveOAuthState(nonce, { orgId, provider: "discord" });
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Failed to save OAuth state for Discord install",
+    );
+    return c.json(
+      { error: "state_save_failed", message: "Could not initiate OAuth flow. Please try again." },
+      500,
+    );
+  }
+
+  const origin = new URL(c.req.url).origin;
+  const redirectUri = `${origin}/api/v1/discord/callback`;
+  // 2048 = Send Messages permission
+  const url =
+    `https://discord.com/oauth2/authorize` +
+    `?client_id=${encodeURIComponent(clientId)}` +
+    `&permissions=2048` +
+    `&scope=bot+applications.commands` +
+    `&response_type=code` +
+    `&redirect_uri=${encodeURIComponent(redirectUri)}` +
+    `&state=${encodeURIComponent(nonce)}`;
+  return c.redirect(url);
+});
+
+// --- GET /api/v1/discord/callback ---
+
+discord.openapi(callbackRoute, async (c) => {
+  const clientId = process.env.DISCORD_CLIENT_ID;
+  const clientSecret = process.env.DISCORD_CLIENT_SECRET;
+  if (!clientId || !clientSecret) {
+    return c.json({ error: "discord_not_configured", message: "Discord not configured" }, 501);
+  }
+
+  const requestId = crypto.randomUUID();
+
+  // Consume the CSRF nonce first — even if the user denied authorization,
+  // the nonce must be consumed to prevent replay attacks.
+  const nonce = c.req.query("state");
+  if (!nonce) {
+    return c.json({ error: "invalid_state", message: "Invalid or expired state parameter." }, 400);
+  }
+
+  let oauthState: Awaited<ReturnType<typeof consumeOAuthState>>;
+  try {
+    oauthState = await consumeOAuthState(nonce);
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err.message : String(err), requestId },
+      "Failed to validate OAuth state — internal database may be unavailable",
+    );
+    return c.html(
+      `<html><body><h1>Installation Failed</h1><p>Could not validate the authorization. Please try again. (ref: ${requestId.slice(0, 8)})</p></body></html>`,
+      500,
+    );
+  }
+
+  if (!oauthState) {
+    return c.json({ error: "invalid_state", message: "Invalid or expired state parameter. Please start the installation again." }, 400);
+  }
+
+  if (oauthState.provider !== "discord") {
+    log.warn({ expected: "discord", got: oauthState.provider, requestId }, "OAuth state provider mismatch");
+    return c.json({ error: "invalid_state", message: "Invalid state parameter." }, 400);
+  }
+
+  // Check for error from Discord (user denied authorization)
+  const errorCode = c.req.query("error");
+  if (errorCode) {
+    const errorDesc = c.req.query("error_description") ?? "Authorization was not granted";
+    log.info({ errorCode, errorDesc }, "Discord authorization denied");
+    return c.json(
+      { error: "authorization_denied", message: errorDesc },
+      400,
+    );
+  }
+
+  const code = c.req.query("code");
+  if (!code) {
+    return c.json({ error: "missing_code", message: "Missing authorization code" }, 400);
+  }
+
+  // Exchange authorization code for token response (contains guild info)
+  const origin = new URL(c.req.url).origin;
+  const redirectUri = `${origin}/api/v1/discord/callback`;
+
+  let tokenData: Record<string, unknown>;
+  try {
+    const tokenRes = await fetch("https://discord.com/api/oauth2/token", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        client_id: clientId,
+        client_secret: clientSecret,
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri,
+      }),
+    });
+
+    if (!tokenRes.ok) {
+      const body = await tokenRes.text();
+      log.error({ status: tokenRes.status, body, requestId }, "Discord token exchange failed");
+      return c.html(
+        `<html><body><h1>Installation Failed</h1><p>Could not exchange authorization code. Please try again. (ref: ${requestId.slice(0, 8)})</p></body></html>`,
+        500,
+      );
+    }
+
+    tokenData = (await tokenRes.json()) as Record<string, unknown>;
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err.message : String(err), requestId },
+      "Discord token exchange request failed",
+    );
+    return c.html(
+      `<html><body><h1>Installation Failed</h1><p>Could not contact Discord. Please try again. (ref: ${requestId.slice(0, 8)})</p></body></html>`,
+      500,
+    );
+  }
+
+  // Extract guild info from the token response
+  const guild = tokenData.guild as { id?: string; name?: string } | undefined;
+  const guildId = guild?.id;
+  const guildName = guild?.name ?? null;
+
+  if (!guildId || typeof guildId !== "string") {
+    log.error(
+      { hasGuild: !!tokenData.guild, tokenType: tokenData.token_type, requestId },
+      "Discord token response missing guild.id",
+    );
+    return c.html(
+      `<html><body><h1>Installation Failed</h1><p>Discord did not return guild information. Please try again. (ref: ${requestId.slice(0, 8)})</p></body></html>`,
+      500,
+    );
+  }
+
+  try {
+    const orgId = oauthState.orgId;
+    await saveDiscordInstallation(guildId, {
+      orgId,
+      guildName: guildName ?? undefined,
+    });
+    log.info({ guildId, guildName, orgId }, "Discord installation saved");
+  } catch (saveErr) {
+    log.error(
+      { err: saveErr instanceof Error ? saveErr.message : String(saveErr), guildId, requestId },
+      "Failed to save Discord installation",
+    );
+    return c.html(
+      `<html><body><h1>Installation Failed</h1><p>Could not save the installation. Please try again. (ref: ${requestId.slice(0, 8)})</p></body></html>`,
+      500,
+    );
+  }
+
+  return c.html(
+    "<html><body><h1>Atlas installed!</h1><p>You can now use Atlas in your Discord server.</p></body></html>",
+  );
+});
+
+export { discord };

package/templates/nextjs-standalone/src/api/routes/ee-error-handler.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared Hono onError handler for admin routes.
+ *
+ * Surfaces HTTPExceptions (thrown by runEffect/runHandler or framework
+ * validation) as JSON responses. Unhandled errors re-throw to Hono's
+ * default handler.
+ *
+ * Enterprise/domain error → HTTP mapping is now centralized in
+ * `lib/effect/hono.ts` via `classifyError`. This module only provides
+ * the router-level onError glue.
+ */
+
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+/**
+ * Shared Hono onError handler for admin routes.
+ *
+ * Returns the pre-built response for HTTPExceptions (from runEffect or
+ * framework validation). Bare 400s without a response body get a generic
+ * JSON body for malformed-JSON errors. Everything else re-throws to
+ * Hono's default handler.
+ */
+export function eeOnError(err: Error, c: Context): Response {
+  if (err instanceof HTTPException) {
+    if (err.res) return err.res;
+    if (err.status === 400) {
+      return c.json({ error: "bad_request", message: "Invalid JSON body." }, 400);
+    }
+  }
+  throw err;
+}

package/templates/nextjs-standalone/src/api/routes/health.ts

@@ -1,11 +1,14 @@
 /**
  * Health check route — public, no auth.
  *
- * Probes datasource, internal DB, semantic layer, explore backend,
- * and auth mode.
+ * Probes datasource and internal DB. Reports config-derived status of
+ * LLM provider, semantic layer, explore backend, auth mode, scheduler,
+ * and Slack. Returns both a flat `checks` object (legacy) and a
+ * structured `components` object for the admin dashboard.
  */
 
-import { Hono } from "hono";
+import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { validationHook } from "./validation-hook";
 import { z } from "zod";
 import {
   validateEnvironment,
@@ -17,6 +20,7 @@ import { createLogger } from "@atlas/api/lib/logger";
 import { getExploreBackendType, getActiveSandboxPluginId } from "@atlas/api/lib/tools/explore";
 import { detectAuthMode } from "@atlas/api/lib/auth/detect";
 import { SENSITIVE_PATTERNS } from "@atlas/api/lib/security";
+import { getSetting } from "@atlas/api/lib/settings";
 
 const log = createLogger("health");
 
@@ -26,9 +30,28 @@ const log = createLogger("health");
 
 const CheckStatusSchema = z.enum(["ok", "error", "not_configured"]);
 
+const ComponentStatusSchema = z.enum(["healthy", "degraded", "down", "disabled"]);
+
+const ComponentHealthSchema = z.object({
+  status: ComponentStatusSchema,
+  latencyMs: z.number().int().nonnegative().optional(),
+  lastCheckedAt: z.string(),
+  message: z.string().optional(),
+  model: z.string().optional(),
+  backend: z.string().optional(),
+});
+
 export const HealthResponseSchema = z.object({
   status: z.enum(["ok", "degraded", "error"]),
   warnings: z.array(z.string()).optional(),
+  brandColor: z.string().optional(),
+  components: z.object({
+    datasource: ComponentHealthSchema,
+    internalDb: ComponentHealthSchema,
+    provider: ComponentHealthSchema,
+    scheduler: ComponentHealthSchema,
+    sandbox: ComponentHealthSchema,
+  }).optional(),
   checks: z.object({
     datasource: z.object({
       status: CheckStatusSchema,
@@ -83,9 +106,39 @@ function findDiagnostic(
   return diagnostics.find((d) => codes.includes(d.code));
 }
 
-const health = new Hono();
+const HealthErrorSchema = z.object({
+  status: z.string(),
+  error: z.string(),
+});
+
+const healthRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Health"],
+  summary: "Health check",
+  description:
+    "Returns the health status of the Atlas API including checks for datasource connectivity, LLM provider, semantic layer, internal database, explore backend, auth mode, and Slack integration. " +
+    "Returns HTTP 200 for 'ok' or 'degraded' status, and 503 for 'error' status.",
+  responses: {
+    200: {
+      description:
+        "Service is healthy or degraded (some optional components unavailable)",
+      content: { "application/json": { schema: HealthResponseSchema } },
+    },
+    503: {
+      description: "Service is unhealthy (critical component failure)",
+      content: {
+        "application/json": {
+          schema: z.union([HealthResponseSchema, HealthErrorSchema]),
+        },
+      },
+    },
+  },
+});
 
-health.get("/", async (c) => {
+const health = new OpenAPIHono({ defaultHook: validationHook });
+
+health.openapi(healthRoute, async (c) => {
   try {
     const diagnostics = await validateEnvironment();
 
@@ -178,7 +231,7 @@ health.get("/", async (c) => {
       status = "degraded";
     else status = "ok";
 
-    const warnings = getStartupWarnings();
+    const warnings = [...getStartupWarnings()];
 
     // Per-source health from ConnectionRegistry
     let sourcesSection: Record<string, { status: string; latencyMs?: number; message?: string; checkedAt?: string; dbType: string }> | undefined;
@@ -228,34 +281,88 @@ health.get("/", async (c) => {
       );
     }
 
+    // Build components section for the health dashboard
+    const now = new Date().toISOString();
+    const schedulerEnabled = process.env.ATLAS_SCHEDULER_ENABLED === "true";
+
+    const components = {
+      datasource: {
+        status: dsNotConfigured
+          ? ("disabled" as const)
+          : hasDsError
+            ? ("down" as const)
+            : ("healthy" as const),
+        ...(dsLatencyMs !== undefined && { latencyMs: dsLatencyMs }),
+        lastCheckedAt: now,
+        ...(hasDsError && {
+          message: dsProbeError ?? dsDiagnostic?.code ?? "DB_UNREACHABLE",
+        }),
+      },
+      internalDb: {
+        status: !process.env.DATABASE_URL
+          ? ("disabled" as const)
+          : hasInternalDbError
+            ? ("down" as const)
+            : ("healthy" as const),
+        ...(internalLatencyMs !== undefined && { latencyMs: internalLatencyMs }),
+        lastCheckedAt: now,
+        ...(hasInternalDbError && {
+          message: internalProbeError ?? "INTERNAL_DB_UNREACHABLE",
+        }),
+      },
+      provider: {
+        status: hasKeyError ? ("down" as const) : ("healthy" as const),
+        model: process.env.ATLAS_MODEL ?? "(default)",
+        lastCheckedAt: now,
+        ...(hasKeyError && { message: "MISSING_API_KEY" }),
+      },
+      // Config-level status only — does not probe the scheduler engine at runtime
+      scheduler: {
+        status: schedulerEnabled ? "healthy" as const : "disabled" as const,
+        lastCheckedAt: now,
+      },
+      // just-bash means no isolation — report degraded so operators know
+      sandbox: {
+        status: exploreBackend === "just-bash" ? "degraded" as const : "healthy" as const,
+        backend: exploreBackend,
+        lastCheckedAt: now,
+        ...(exploreBackend === "just-bash" && { message: "No sandbox isolation — using just-bash fallback" }),
+      },
+    };
+
+    // Brand color for frontend theming (public, no auth required)
+    const brandColor = getSetting("ATLAS_BRAND_COLOR");
+
     const response = {
       status,
       ...(warnings.length > 0 && { warnings }),
+      ...(brandColor && { brandColor }),
+      components,
       checks: {
         datasource: dsNotConfigured
           ? { status: "not_configured" as const }
           : {
-              status: hasDsError ? "error" : "ok",
+              status: (hasDsError ? "error" : "ok") as "error" | "ok",
               ...(dsLatencyMs !== undefined && { latencyMs: dsLatencyMs }),
               ...(hasDsError && {
                 error: dsProbeError ?? dsDiagnostic?.code ?? "DB_UNREACHABLE",
               }),
             },
         provider: {
-          status: hasKeyError ? "error" : "ok",
+          status: (hasKeyError ? "error" : "ok") as "error" | "ok",
           provider,
           model: process.env.ATLAS_MODEL ?? "(default)",
           ...(hasKeyError && { error: "MISSING_API_KEY" }),
         },
         semanticLayer: {
-          status: hasSemanticError ? "error" : "ok",
+          status: (hasSemanticError ? "error" : "ok") as "error" | "ok",
           entityCount,
           ...(hasSemanticError && { error: "MISSING_SEMANTIC_LAYER" }),
         },
         internalDb: !process.env.DATABASE_URL
           ? { status: "not_configured" as const }
           : {
-              status: hasInternalDbError ? "error" : "ok",
+              status: (hasInternalDbError ? "error" : "ok") as "error" | "ok",
               ...(internalLatencyMs !== undefined && {
                 latencyMs: internalLatencyMs,
               }),
@@ -267,12 +374,15 @@ health.get("/", async (c) => {
           backend: exploreBackend,
           isolated: exploreBackend !== "just-bash",
           ...(exploreBackend === "plugin" && { isolationVerified: false }),
-          ...(exploreBackend === "plugin" && getActiveSandboxPluginId() ? { pluginId: getActiveSandboxPluginId() } : {}),
+          ...(() => {
+            const pluginId = exploreBackend === "plugin" ? getActiveSandboxPluginId() : null;
+            return pluginId ? { pluginId } : {};
+          })(),
         },
         auth: {
           mode: authMode,
           enabled: authMode !== "none",
-          ...(hasAuthError && { error: authDiagnostic!.code }),
+          ...(authDiagnostic && { error: authDiagnostic.code }),
         },
         slack: {
           enabled: !!process.env.SLACK_SIGNING_SECRET,
@@ -286,13 +396,18 @@ health.get("/", async (c) => {
       ...(sourcesSection ? { sources: sourcesSection } : {}),
     };
 
-    return c.json(response, response.status === "error" ? 503 : 200);
+    // Health response is built dynamically with many conditional fields — TypeScript
+    // can't statically verify all literal string types against the Zod schema.
+    if (response.status === "error") {
+      return c.json(response as z.infer<typeof HealthResponseSchema>, 503);
+    }
+    return c.json(response as z.infer<typeof HealthResponseSchema>, 200);
   } catch (err) {
     log.error(
       { err: err instanceof Error ? err : new Error(String(err)) },
       "Health endpoint unexpected error",
     );
-    return c.json({ status: "error", error: "health_check_failed" }, 503);
+    return c.json({ status: "error" as const, error: "health_check_failed" }, 503);
   }
 });