@sentry/junior 0.1.1 → 0.3.0

package/README.md

@@ -2,11 +2,6 @@
 
 `@sentry/junior` is a Slack bot package for Next.js apps.
 
-If you are contributing to this monorepo, use the root docs:
-
-- `README.md` for general usage
-- `CONTRIBUTING.md` for development workflows
-
 ## Install
 
 ```bash
@@ -14,18 +9,7 @@ pnpm add @sentry/junior
 pnpm add next react react-dom @sentry/nextjs
 ```
 
-## Required App Files
-
-Add these files under `app/`:
-
-```text
-app/SOUL.md
-app/ABOUT.md
-app/skills/
-app/plugins/ (optional)
-```
-
-## Next.js Integration
+## Quick usage
 
 `app/api/[...path]/route.js`:
 
@@ -45,156 +29,17 @@ export const runtime = "nodejs";
 
 ```js
 import { withJunior } from "@sentry/junior/config";
-export default withJunior();
-```
-
-`instrumentation.js`:
 
-```js
-export { register, onRequestError } from "@sentry/junior/instrumentation";
+export default withJunior({
+  pluginPackages: ["@sentry/junior-github", "@sentry/junior-sentry"]
+});
 ```
 
-If your app does not already include a root layout:
-
-`app/layout.js`:
-
-```js
-export { default } from "@sentry/junior/app/layout";
-```
-
-## Scaffold a New Bot
-
-```bash
-npx junior init my-bot
-cd my-bot
-pnpm install
-pnpm dev
-```
-
-## Deploy on Vercel
-
-Use this flow for a production-ready setup.
-
-### 1) Create and link a Vercel project
-
-Dashboard: `Vercel -> Add New... -> Project`, then import your repo.
-
-CLI:
-
-```bash
-pnpm dlx vercel@latest login
-pnpm dlx vercel@latest link
-```
-
-### 2) Configure required app routes in your Next.js app
-
-Ensure you have these files:
-
-`app/api/[...path]/route.js`:
-
-```js
-export { GET, POST } from "@sentry/junior/handler";
-export const runtime = "nodejs";
-```
-
-`app/api/queue/callback/route.js`:
-
-```js
-export { POST } from "@sentry/junior/handlers/queue-callback";
-export const runtime = "nodejs";
-```
-
-### 3) Configure Vercel Queue
-
-Dashboard: `Project -> Settings -> Functions` (verify queue trigger after deploy).
-
-Add this `vercel.json` trigger:
-
-```json
-{
-  "functions": {
-    "app/api/queue/callback/route.js": {
-      "experimentalTriggers": [
-        {
-          "type": "queue/v2beta",
-          "topic": "junior-thread-message"
-        }
-      ]
-    }
-  }
-}
-```
-
-### 4) Configure Redis (`REDIS_URL`)
-
-Dashboard options:
-
-- Add a Redis integration from `Project -> Storage` (for example Upstash Redis), or
-- Use any external Redis provider and copy its connection URL.
-
-Then set `REDIS_URL` in Vercel env vars.
-
-### 5) Configure environment variables
-
-Set production env vars first, then repeat for `preview` and `development` as needed.
-
-#### Required
-
-- `SLACK_SIGNING_SECRET`
-- `SLACK_BOT_TOKEN` (or `SLACK_BOT_USER_TOKEN`)
-- `REDIS_URL`
-
-CLI:
-
-```bash
-vercel env add SLACK_SIGNING_SECRET production --sensitive
-vercel env add SLACK_BOT_TOKEN production --sensitive
-vercel env add REDIS_URL production --sensitive
-```
-
-#### Recommended
-
-- `JUNIOR_BOT_NAME` (defaults to `junior`)
-- `AI_MODEL` (defaults to `anthropic/claude-sonnet-4.6`)
-- `AI_FAST_MODEL` (defaults to `anthropic/claude-haiku-4.5`)
-
-CLI:
-
-```bash
-vercel env add JUNIOR_BOT_NAME production
-vercel env add AI_MODEL production
-vercel env add AI_FAST_MODEL production
-```
-
-#### Optional
-
-- `JUNIOR_BASE_URL` (set if your canonical external URL differs from Vercel auto-resolved URLs; used for OAuth callback links)
-- `AI_GATEWAY_API_KEY` (optional override; in Vercel runtime, ambient `VERCEL_OIDC_TOKEN` is used automatically for AI gateway auth)
-
-After env changes, redeploy so the new deployment picks up updated values.
-
-### 6) Configure Slack app (external prerequisite)
-
-In Slack app settings:
-
-1. Set request URL(s) to `https://<your-domain>/api/webhooks/slack` for Events and Interactivity.
-2. Install the app to your workspace.
-3. Copy credentials into Vercel env vars:
-   - Bot token -> `SLACK_BOT_TOKEN`
-   - Signing secret -> `SLACK_SIGNING_SECRET`
-
-### 7) Deploy and verify
-
-1. Deploy the app to Vercel.
-2. Confirm health endpoint responds:
-   - `GET https://<your-domain>/api/health`
-3. Mention the bot in Slack and confirm a threaded response arrives.
-4. Confirm queue processing is active in logs (enqueue + callback processing).
-5. Confirm there are no `REDIS_URL is required` runtime errors.
-
-## Plugin Setup
+## Full docs
 
-Core setup above is shared. Plugin-specific requirements are documented in each plugin README:
+Canonical docs: **https://junior.sentry.dev/**
 
-- GitHub: `@sentry/junior-github` -> `packages/junior-github/skills/github/README.md`
-- Sentry: `@sentry/junior-sentry` -> `packages/junior-sentry/README.md`
+- Quickstart: https://junior.sentry.dev/start-here/quickstart/
+- Deployment: https://junior.sentry.dev/start-here/deploy/
+- Plugin setup: https://junior.sentry.dev/extend/plugins-overview/
+- API reference: https://junior.sentry.dev/reference/api/

package/bin/junior.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
-import fs from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const { positionals } = parseArgs({
   allowPositionals: true,
@@ -11,138 +11,48 @@ const { positionals } = parseArgs({
 
 const command = positionals[0];
 
-function writeWrapperFiles(targetDir) {
-  // app/api/[...path]/route.js
-  const routeDir = path.join(targetDir, "app", "api", "[...path]");
-  fs.mkdirSync(routeDir, { recursive: true });
-  fs.writeFileSync(
-    path.join(routeDir, "route.js"),
-    'export { GET, POST } from "@sentry/junior/handler";\n' +
-      'export const runtime = "nodejs";\n'
-  );
-
-  // app/api/queue/callback/route.js
-  const queueRouteDir = path.join(targetDir, "app", "api", "queue", "callback");
-  fs.mkdirSync(queueRouteDir, { recursive: true });
-  fs.writeFileSync(
-    path.join(queueRouteDir, "route.js"),
-    'export { POST } from "@sentry/junior/handlers/queue-callback";\n' +
-      'export const runtime = "nodejs";\n'
-  );
-
-  // app/layout.js
-  fs.mkdirSync(path.join(targetDir, "app"), { recursive: true });
-  fs.writeFileSync(
-    path.join(targetDir, "app", "layout.js"),
-    'export { default } from "@sentry/junior/app/layout";\n'
-  );
+async function loadCliFunction(moduleName, exportName, unavailableMessage) {
+  const currentFile = fileURLToPath(import.meta.url);
+  const modulePath = path.join(path.dirname(currentFile), "..", "dist", "cli", `${moduleName}.js`);
+  const moduleUrl = pathToFileURL(modulePath).href;
+  const loadedModule = await import(moduleUrl);
+  if (typeof loadedModule[exportName] !== "function") {
+    throw new Error(unavailableMessage);
+  }
+  return loadedModule[exportName];
+}
 
-  // next.config.mjs
-  fs.writeFileSync(
-    path.join(targetDir, "next.config.mjs"),
-    'import { withJunior } from "@sentry/junior/config";\n' +
-      'export default withJunior();\n'
+async function runSnapshotCreate() {
+  const runSnapshotCreateFn = await loadCliFunction(
+    "snapshot-warmup",
+    "runSnapshotCreate",
+    "Snapshot create module is unavailable; reinstall @sentry/junior and retry."
   );
+  await runSnapshotCreateFn();
+}
 
-  // instrumentation.js
-  fs.writeFileSync(
-    path.join(targetDir, "instrumentation.js"),
-    'export { register, onRequestError } from "@sentry/junior/instrumentation";\n'
-  );
+async function runInit(dir) {
+  const runInitFn = await loadCliFunction("init", "runInit", "Init module is unavailable; reinstall @sentry/junior and retry.");
+  await runInitFn(dir);
 }
 
-// ---------------------------------------------------------------------------
-// junior init <dir>
-// ---------------------------------------------------------------------------
-if (command === "init") {
-  const dir = positionals[1];
-  if (!dir) {
-    console.error("usage: junior init <dir>");
-    process.exit(1);
+async function main() {
+  const runCli = await loadCliFunction(
+    "run",
+    "runCli",
+    "CLI dispatcher module is unavailable; reinstall @sentry/junior and retry."
+  );
+  const exitCode = await runCli(positionals, {
+    runInit,
+    runSnapshotCreate
+  });
+  if (exitCode !== 0) {
+    process.exit(exitCode);
   }
-
-  const target = path.resolve(dir);
-  fs.mkdirSync(target, { recursive: true });
-
-  const name = path.basename(target);
-
-  // package.json
-  const pkg = {
-    name,
-    version: "0.1.0",
-    private: true,
-    type: "module",
-    scripts: {
-      dev: "next dev",
-      build: "next build",
-      start: "next start"
-    },
-    dependencies: {
-      "@sentry/junior": "latest",
-      next: "^16.0.0",
-      react: "^19.0.0",
-      "react-dom": "^19.0.0",
-      "@sentry/nextjs": "^10.0.0"
-    }
-  };
-  fs.writeFileSync(
-    path.join(target, "package.json"),
-    JSON.stringify(pkg, null, 2) + "\n"
-  );
-
-  // app/data/SOUL.md
-  const dataDir = path.join(target, "app", "data");
-  fs.mkdirSync(dataDir, { recursive: true });
-  fs.writeFileSync(
-    path.join(dataDir, "SOUL.md"),
-    `# ${name}\n\nYou are ${name}, a helpful assistant.\n`
-  );
-
-  // app/skills/
-  const skillsDir = path.join(target, "app", "skills");
-  fs.mkdirSync(skillsDir, { recursive: true });
-  fs.writeFileSync(path.join(skillsDir, ".gitkeep"), "");
-
-  // app/plugins/
-  const pluginsDir = path.join(target, "app", "plugins");
-  fs.mkdirSync(pluginsDir, { recursive: true });
-  fs.writeFileSync(path.join(pluginsDir, ".gitkeep"), "");
-
-  // .gitignore
-  fs.writeFileSync(
-    path.join(target, ".gitignore"),
-    [
-      "node_modules/",
-      ".next/",
-      ".env",
-      ".env.local",
-      ""
-    ].join("\n")
-  );
-
-  // .env.example
-  fs.writeFileSync(
-    path.join(target, ".env.example"),
-    [
-      "SLACK_BOT_TOKEN=",
-      "SLACK_SIGNING_SECRET=",
-      "JUNIOR_BOT_NAME=",
-      "AI_MODEL=",
-      "AI_FAST_MODEL=",
-      "REDIS_URL=",
-      "NEXT_PUBLIC_SENTRY_DSN=",
-      ""
-    ].join("\n")
-  );
-
-  writeWrapperFiles(target);
-
-  console.log(`Created ${name} at ${target}`);
-  console.log();
-  console.log(`  cd ${dir} && pnpm install && pnpm dev`);
-  console.log();
-  process.exit(0);
 }
 
-console.error("usage: junior init <dir>");
-process.exit(1);
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`junior command failed: ${message}`);
+  process.exit(1);
+});

package/dist/app/layout.d.ts

@@ -1,6 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
+/**
+ * Minimal root layout export for apps that do not provide one yet.
+ */
 declare function RootLayout({ children }: {
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;

package/dist/{bot-6KXJ366H.js → bot-JSIREVQD.js}

@@ -4,9 +4,10 @@ import {
   createNormalizingStream,
   resetBotDepsForTests,
   setBotDepsForTests
-} from "./chunk-CJFEZLEN.js";
-import "./chunk-5LLCJPTH.js";
-import "./chunk-BBOVH5RF.js";
+} from "./chunk-L745IWNK.js";
+import "./chunk-DPTR2FNH.js";
+import "./chunk-PY4AI2GZ.js";
+import "./chunk-SP6LV35L.js";
 export {
   appSlackRuntime,
   bot,

package/dist/chunk-4RFOJSJL.js

@@ -0,0 +1,272 @@
+import {
+  appSlackRuntime,
+  createQueueCallbackHandler,
+  downloadPrivateSlackFile,
+  getThreadMessageTopic,
+  removeReactionFromMessage
+} from "./chunk-L745IWNK.js";
+import {
+  acquireQueueMessageProcessingOwnership,
+  completeQueueMessageProcessingOwnership,
+  failQueueMessageProcessingOwnership,
+  getQueueMessageProcessingState,
+  getStateAdapter,
+  refreshQueueMessageProcessingOwnership
+} from "./chunk-DPTR2FNH.js";
+import {
+  createRequestContext,
+  logError,
+  logException,
+  logWarn,
+  setSpanStatus,
+  withContext,
+  withSpan
+} from "./chunk-PY4AI2GZ.js";
+
+// src/chat/queue/process-thread-message.ts
+import { Message, ThreadImpl } from "chat";
+
+// src/chat/thread-runtime/process-thread-message-runtime.ts
+function rehydrateAttachmentFetchers(payload) {
+  for (const attachment of payload.message.attachments) {
+    if (!attachment.fetchData && attachment.url) {
+      attachment.fetchData = () => downloadPrivateSlackFile(attachment.url);
+    }
+  }
+}
+async function processThreadMessageRuntime(args) {
+  const runtimePayload = {
+    message: args.message,
+    thread: args.thread
+  };
+  rehydrateAttachmentFetchers(runtimePayload);
+  if (args.kind === "new_mention") {
+    await appSlackRuntime.handleNewMention(args.thread, args.message, {
+      beforeFirstResponsePost: args.beforeFirstResponsePost
+    });
+    return;
+  }
+  if (args.kind === "subscribed_reply") {
+    await appSlackRuntime.handleSubscribedMessage(args.thread, args.message, {
+      beforeFirstResponsePost: args.beforeFirstResponsePost,
+      preApprovedReply: true
+    });
+    return;
+  }
+  await appSlackRuntime.handleSubscribedMessage(args.thread, args.message, {
+    beforeFirstResponsePost: args.beforeFirstResponsePost
+  });
+}
+
+// src/chat/queue/process-thread-message.ts
+var stateAdapterConnected = false;
+function isSerializedThread(thread) {
+  return typeof thread === "object" && thread !== null && thread._type === "chat:Thread";
+}
+function isSerializedMessage(message) {
+  return typeof message === "object" && message !== null && message._type === "chat:Message";
+}
+function getPayloadChannelId(payload) {
+  return payload.thread.channelId;
+}
+function getPayloadUserId(payload) {
+  return payload.message.author?.userId;
+}
+function createMessageOwnerToken() {
+  return `msg-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+var QueueMessageOwnershipError = class extends Error {
+  constructor(stage, dedupKey) {
+    super(`Queue message ownership lost during ${stage} for dedupKey=${dedupKey}`);
+    this.name = "QueueMessageOwnershipError";
+  }
+};
+var defaultProcessQueuedThreadMessageDeps = {
+  clearProcessingReaction: async ({ channelId, timestamp }) => {
+    await removeReactionFromMessage({
+      channelId,
+      timestamp,
+      emoji: "eyes"
+    });
+  },
+  logWarn,
+  processRuntime: processThreadMessageRuntime
+};
+function deserializeThread(thread) {
+  if (isSerializedThread(thread)) {
+    return ThreadImpl.fromJSON(thread);
+  }
+  return thread;
+}
+function deserializeMessage(message) {
+  if (isSerializedMessage(message)) {
+    return Message.fromJSON(message);
+  }
+  return message;
+}
+async function logThreadMessageFailure(payload, errorMessage) {
+  logError(
+    "queue_message_failed",
+    {
+      slackThreadId: payload.normalizedThreadId,
+      slackChannelId: getPayloadChannelId(payload),
+      slackUserId: getPayloadUserId(payload)
+    },
+    {
+      "messaging.message.id": payload.message.id,
+      "app.queue.message_kind": payload.kind,
+      "app.queue.message_id": payload.queueMessageId,
+      "error.message": errorMessage
+    },
+    "Queue message processing failed"
+  );
+}
+async function processQueuedThreadMessage(payload, deps = defaultProcessQueuedThreadMessageDeps) {
+  const existingMessageState = await getQueueMessageProcessingState(payload.dedupKey);
+  if (existingMessageState?.status === "completed") {
+    return;
+  }
+  const ownerToken = createMessageOwnerToken();
+  const claimResult = await acquireQueueMessageProcessingOwnership({
+    rawKey: payload.dedupKey,
+    ownerToken,
+    queueMessageId: payload.queueMessageId
+  });
+  if (claimResult === "blocked") {
+    return;
+  }
+  const threadWasSerialized = isSerializedThread(payload.thread);
+  if (threadWasSerialized && !stateAdapterConnected) {
+    await getStateAdapter().connect();
+    stateAdapterConnected = true;
+  }
+  const runtimePayload = {
+    ...payload,
+    thread: deserializeThread(payload.thread),
+    message: deserializeMessage(payload.message)
+  };
+  try {
+    const refreshed = await refreshQueueMessageProcessingOwnership({
+      rawKey: payload.dedupKey,
+      ownerToken,
+      queueMessageId: payload.queueMessageId
+    });
+    if (!refreshed) {
+      throw new QueueMessageOwnershipError("refresh", payload.dedupKey);
+    }
+    let reactionCleared = false;
+    const clearReactionBeforeFirstResponsePost = async () => {
+      if (reactionCleared) {
+        return;
+      }
+      reactionCleared = true;
+      try {
+        await deps.clearProcessingReaction({
+          channelId: runtimePayload.thread.channelId,
+          timestamp: runtimePayload.message.id
+        });
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        deps.logWarn(
+          "queue_processing_reaction_clear_failed",
+          {
+            slackThreadId: payload.normalizedThreadId,
+            slackChannelId: getPayloadChannelId(payload),
+            slackUserId: getPayloadUserId(payload)
+          },
+          {
+            "messaging.message.id": payload.message.id,
+            "app.queue.message_kind": payload.kind,
+            "app.queue.message_id": payload.queueMessageId,
+            "error.message": errorMessage
+          },
+          "Failed to remove processing reaction before sending queue response"
+        );
+      }
+    };
+    await deps.processRuntime({
+      kind: runtimePayload.kind,
+      thread: runtimePayload.thread,
+      message: runtimePayload.message,
+      beforeFirstResponsePost: clearReactionBeforeFirstResponsePost
+    });
+    const completed = await completeQueueMessageProcessingOwnership({
+      rawKey: payload.dedupKey,
+      ownerToken,
+      queueMessageId: payload.queueMessageId
+    });
+    if (!completed) {
+      throw new QueueMessageOwnershipError("complete", payload.dedupKey);
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    await logThreadMessageFailure(payload, errorMessage);
+    const failed = await failQueueMessageProcessingOwnership({
+      rawKey: payload.dedupKey,
+      ownerToken,
+      errorMessage,
+      queueMessageId: payload.queueMessageId
+    });
+    if (!failed && !(error instanceof QueueMessageOwnershipError)) {
+      throw new Error(`Failed to persist queue message failure state for dedupKey=${payload.dedupKey}: ${errorMessage}`);
+    }
+    throw error;
+  }
+}
+
+// src/handlers/queue-callback.ts
+var callbackHandler = createQueueCallbackHandler(async (message, metadata) => {
+  if (metadata.topicName === getThreadMessageTopic()) {
+    const payload = {
+      ...message,
+      queueMessageId: metadata.messageId
+    };
+    await withSpan(
+      "queue.process_message",
+      "queue.process_message",
+      {
+        slackThreadId: payload.normalizedThreadId,
+        slackChannelId: payload.thread.channelId,
+        slackUserId: payload.message.author?.userId
+      },
+      async () => {
+        await processQueuedThreadMessage(payload);
+      },
+      {
+        "messaging.message.id": payload.message.id,
+        "app.queue.message_kind": payload.kind,
+        "app.queue.message_id": payload.queueMessageId,
+        "app.queue.delivery_count": metadata.deliveryCount,
+        "app.queue.topic": metadata.topicName
+      }
+    );
+    return;
+  }
+  throw new Error(`Unexpected queue topic: ${metadata.topicName}`);
+});
+async function POST(request) {
+  const requestContext = createRequestContext(request, { platform: "queue" });
+  return withContext(requestContext, async () => {
+    try {
+      const response = await callbackHandler(request);
+      setSpanStatus(response.status >= 500 ? "error" : "ok");
+      return response;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logError(
+        "queue_callback_failed",
+        {},
+        {
+          "error.message": message
+        },
+        "Queue callback processing failed"
+      );
+      logException(error, "queue_callback_failed");
+      throw error;
+    }
+  });
+}
+
+export {
+  POST
+};