@sentry/junior-plugin-api 0.63.0 → 0.65.0

package/dist/index.d.ts

@@ -171,14 +171,93 @@ export interface AgentPluginHooks {
     heartbeat?(ctx: HeartbeatHookContext): Promise<HeartbeatResult | void> | HeartbeatResult | void;
     slackConversationLink?(ctx: SlackConversationLinkHookContext): SlackConversationLink | undefined;
 }
-export interface JuniorPluginConfig {
-    legacyStatePrefixes?: string[];
-    packages?: string[];
+export interface JuniorPluginOAuthConfig {
+    authorizeEndpoint: string;
+    authorizeParams?: Record<string, string>;
+    clientIdEnv: string;
+    clientSecretEnv: string;
+    scope?: string;
+    tokenAuthMethod?: "body" | "basic";
+    tokenEndpoint: string;
+    tokenExtraHeaders?: Record<string, string>;
+}
+export interface JuniorPluginOAuthBearerCredentials {
+    apiHeaders?: Record<string, string>;
+    authTokenEnv: string;
+    authTokenPlaceholder?: string;
+    domains: string[];
+    type: "oauth-bearer";
+}
+export interface JuniorPluginGitHubAppCredentials {
+    apiHeaders?: Record<string, string>;
+    appIdEnv: string;
+    authTokenEnv: string;
+    authTokenPlaceholder?: string;
+    domains: string[];
+    installationIdEnv: string;
+    privateKeyEnv: string;
+    type: "github-app";
+}
+export type JuniorPluginCredentials = JuniorPluginOAuthBearerCredentials | JuniorPluginGitHubAppCredentials;
+export interface JuniorPluginNpmRuntimeDependency {
+    package: string;
+    type: "npm";
+    version: string;
+}
+export interface JuniorPluginSystemRuntimeDependency {
+    package: string;
+    type: "system";
+}
+export interface JuniorPluginSystemRuntimeDependencyFromUrl {
+    sha256: string;
+    type: "system";
+    url: string;
+}
+export type JuniorPluginRuntimeDependency = JuniorPluginNpmRuntimeDependency | JuniorPluginSystemRuntimeDependency | JuniorPluginSystemRuntimeDependencyFromUrl;
+export interface JuniorPluginRuntimePostinstallCommand {
+    args?: string[];
+    cmd: string;
+    sudo?: boolean;
 }
-export interface JuniorPlugin {
+export interface JuniorPluginMcpConfig {
+    allowedTools?: string[];
+    headers?: Record<string, string>;
+    transport: "http";
+    url: string;
+}
+export interface JuniorPluginEnvVarDeclaration {
+    default?: string;
+    exposeToCommandEnv?: boolean;
+}
+export interface JuniorPluginManifest {
+    apiHeaders?: Record<string, string>;
+    capabilities?: string[];
+    commandEnv?: Record<string, string>;
+    configKeys?: string[];
+    credentials?: JuniorPluginCredentials;
+    description: string;
+    domains?: string[];
+    envVars?: Record<string, JuniorPluginEnvVarDeclaration>;
+    mcp?: JuniorPluginMcpConfig;
+    name: string;
+    oauth?: JuniorPluginOAuthConfig;
+    runtimeDependencies?: JuniorPluginRuntimeDependency[];
+    runtimePostinstall?: JuniorPluginRuntimePostinstallCommand[];
+    target?: {
+        commandFlags?: string[];
+        configKey: string;
+        type: string;
+    };
+}
+export type JuniorPluginRegistrationInput = {
     hooks?: AgentPluginHooks;
+    legacyStatePrefixes?: string[];
+    manifest: JuniorPluginManifest;
+    name?: string;
+    packageName?: string;
+};
+export interface JuniorPluginRegistration extends JuniorPluginRegistrationInput {
     name: string;
-    pluginConfig?: JuniorPluginConfig;
 }
-/** Define a trusted Junior plugin with optional package config and agent hooks. */
-export declare function defineJuniorPlugin(plugin: JuniorPlugin): JuniorPlugin;
+/** Define one Junior plugin registration for app and build-time wiring. */
+export declare function defineJuniorPlugin(plugin: JuniorPluginRegistrationInput): JuniorPluginRegistration;

package/dist/index.js

@@ -5,8 +5,44 @@ var AgentPluginToolInputError = class extends Error {
     this.name = "AgentPluginToolInputError";
   }
 };
+var PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
 function defineJuniorPlugin(plugin) {
-  return plugin;
+  if ("pluginConfig" in plugin) {
+    throw new Error(
+      "pluginConfig is no longer supported. Put runtime metadata in manifest and trusted state prefixes on the plugin registration."
+    );
+  }
+  const manifest = plugin.manifest;
+  if (!manifest) {
+    throw new Error(
+      "defineJuniorPlugin() requires a manifest. Use a package name string in defineJuniorPlugins([...]) for plugin.yaml packages."
+    );
+  }
+  const name = plugin.name ?? manifest.name;
+  if (!name) {
+    throw new Error(
+      "Junior plugin registrations must include name or manifest.name."
+    );
+  }
+  if (!PLUGIN_NAME_RE.test(name)) {
+    throw new Error(
+      `Junior plugin registration name "${name}" must be a lowercase plugin identifier.`
+    );
+  }
+  if (typeof manifest.description !== "string" || !manifest.description.trim()) {
+    throw new Error(
+      `Junior plugin "${name}" manifest.description is required.`
+    );
+  }
+  if (plugin.name && manifest.name && plugin.name !== manifest.name) {
+    throw new Error(
+      `Junior plugin registration name "${plugin.name}" must match manifest.name "${manifest.name}".`
+    );
+  }
+  return {
+    ...plugin,
+    name
+  };
 }
 export {
   AgentPluginToolInputError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-plugin-api",
-  "version": "0.63.0",
+  "version": "0.65.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -222,18 +222,156 @@ export interface AgentPluginHooks {
   ): SlackConversationLink | undefined;
 }
 
-export interface JuniorPluginConfig {
-  legacyStatePrefixes?: string[];
-  packages?: string[];
+export interface JuniorPluginOAuthConfig {
+  authorizeEndpoint: string;
+  authorizeParams?: Record<string, string>;
+  clientIdEnv: string;
+  clientSecretEnv: string;
+  scope?: string;
+  tokenAuthMethod?: "body" | "basic";
+  tokenEndpoint: string;
+  tokenExtraHeaders?: Record<string, string>;
+}
+
+export interface JuniorPluginOAuthBearerCredentials {
+  apiHeaders?: Record<string, string>;
+  authTokenEnv: string;
+  authTokenPlaceholder?: string;
+  domains: string[];
+  type: "oauth-bearer";
+}
+
+export interface JuniorPluginGitHubAppCredentials {
+  apiHeaders?: Record<string, string>;
+  appIdEnv: string;
+  authTokenEnv: string;
+  authTokenPlaceholder?: string;
+  domains: string[];
+  installationIdEnv: string;
+  privateKeyEnv: string;
+  type: "github-app";
+}
+
+export type JuniorPluginCredentials =
+  | JuniorPluginOAuthBearerCredentials
+  | JuniorPluginGitHubAppCredentials;
+
+export interface JuniorPluginNpmRuntimeDependency {
+  package: string;
+  type: "npm";
+  version: string;
+}
+
+export interface JuniorPluginSystemRuntimeDependency {
+  package: string;
+  type: "system";
+}
+
+export interface JuniorPluginSystemRuntimeDependencyFromUrl {
+  sha256: string;
+  type: "system";
+  url: string;
+}
+
+export type JuniorPluginRuntimeDependency =
+  | JuniorPluginNpmRuntimeDependency
+  | JuniorPluginSystemRuntimeDependency
+  | JuniorPluginSystemRuntimeDependencyFromUrl;
+
+export interface JuniorPluginRuntimePostinstallCommand {
+  args?: string[];
+  cmd: string;
+  sudo?: boolean;
+}
+
+export interface JuniorPluginMcpConfig {
+  allowedTools?: string[];
+  headers?: Record<string, string>;
+  transport: "http";
+  url: string;
+}
+
+export interface JuniorPluginEnvVarDeclaration {
+  default?: string;
+  exposeToCommandEnv?: boolean;
 }
 
-export interface JuniorPlugin {
+export interface JuniorPluginManifest {
+  apiHeaders?: Record<string, string>;
+  capabilities?: string[];
+  commandEnv?: Record<string, string>;
+  configKeys?: string[];
+  credentials?: JuniorPluginCredentials;
+  description: string;
+  domains?: string[];
+  envVars?: Record<string, JuniorPluginEnvVarDeclaration>;
+  mcp?: JuniorPluginMcpConfig;
+  name: string;
+  oauth?: JuniorPluginOAuthConfig;
+  runtimeDependencies?: JuniorPluginRuntimeDependency[];
+  runtimePostinstall?: JuniorPluginRuntimePostinstallCommand[];
+  target?: {
+    commandFlags?: string[];
+    configKey: string;
+    type: string;
+  };
+}
+
+export type JuniorPluginRegistrationInput = {
   hooks?: AgentPluginHooks;
+  legacyStatePrefixes?: string[];
+  manifest: JuniorPluginManifest;
+  name?: string;
+  packageName?: string;
+};
+
+export interface JuniorPluginRegistration extends JuniorPluginRegistrationInput {
   name: string;
-  pluginConfig?: JuniorPluginConfig;
 }
 
-/** Define a trusted Junior plugin with optional package config and agent hooks. */
-export function defineJuniorPlugin(plugin: JuniorPlugin): JuniorPlugin {
-  return plugin;
+const PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+/** Define one Junior plugin registration for app and build-time wiring. */
+export function defineJuniorPlugin(
+  plugin: JuniorPluginRegistrationInput,
+): JuniorPluginRegistration {
+  if ("pluginConfig" in plugin) {
+    throw new Error(
+      "pluginConfig is no longer supported. Put runtime metadata in manifest and trusted state prefixes on the plugin registration.",
+    );
+  }
+  const manifest = plugin.manifest;
+  if (!manifest) {
+    throw new Error(
+      "defineJuniorPlugin() requires a manifest. Use a package name string in defineJuniorPlugins([...]) for plugin.yaml packages.",
+    );
+  }
+  const name = plugin.name ?? manifest.name;
+  if (!name) {
+    throw new Error(
+      "Junior plugin registrations must include name or manifest.name.",
+    );
+  }
+  if (!PLUGIN_NAME_RE.test(name)) {
+    throw new Error(
+      `Junior plugin registration name "${name}" must be a lowercase plugin identifier.`,
+    );
+  }
+  if (
+    typeof manifest.description !== "string" ||
+    !manifest.description.trim()
+  ) {
+    throw new Error(
+      `Junior plugin "${name}" manifest.description is required.`,
+    );
+  }
+  if (plugin.name && manifest.name && plugin.name !== manifest.name) {
+    throw new Error(
+      `Junior plugin registration name "${plugin.name}" must match manifest.name "${manifest.name}".`,
+    );
+  }
+  return {
+    ...plugin,
+    name,
+  };
 }