feat(apps): declare envMappings for every app; make field required

apps/web/src/lib/apps/github-enterprise.ts

@@ -1,5 +1,9 @@
 import type { AppDefinition } from "./types";
-import { buildGithubAuthUrl, exchangeGithubCode } from "./github-oauth";
+import {
+  buildGithubAuthUrl,
+  exchangeGithubCode,
+  githubEnvMappings,
+} from "./github-oauth";
 
 const cfgFromConfig = (config: Record<string, string>) => {
   const baseUrl = config.baseUrl;
@@ -115,4 +119,5 @@ export const githubEnterprise: AppDefinition = {
       clientSecret: "GITHUB_ENTERPRISE_CLIENT_SECRET",
     },
   },
+  envMappings: githubEnvMappings,
 };

apps/web/src/lib/apps/github-oauth.ts

@@ -1,3 +1,4 @@
+import type { EnvMapping } from "@/lib/env-mapping";
 import type {
   OAuthBuildAuthUrlParams,
   OAuthExchangeCodeParams,
@@ -9,6 +10,17 @@ export interface GithubOAuthConfig {
   apiBase: string;
 }
 
+/**
+ * Env var contract for GitHub OAuth connections (github.com + Enterprise).
+ * `gh` CLI, hub, and octokit-based tools read `GH_TOKEN` by default; the
+ * gateway swaps the sentinel for the real OAuth access token on outbound
+ * requests to `api.github.com`, `github.com`, and `raw.githubusercontent.com`
+ * (see gateway `apps.rs`).
+ */
+export const githubEnvMappings: EnvMapping[] = [
+  { envName: "GH_TOKEN", placeholder: "humr:sentinel" },
+];
+
 export const buildGithubAuthUrl = (
   cfg: GithubOAuthConfig,
   params: OAuthBuildAuthUrlParams,

apps/web/src/lib/apps/github.ts

@@ -2,6 +2,7 @@ import type { AppDefinition } from "./types";
 import {
   buildGithubAuthUrl,
   exchangeGithubCode,
+  githubEnvMappings,
   type GithubOAuthConfig,
 } from "./github-oauth";
 
@@ -94,4 +95,5 @@ export const github: AppDefinition = {
       clientSecret: "GITHUB_CLIENT_SECRET",
     },
   },
+  envMappings: githubEnvMappings,
 };

apps/web/src/lib/apps/resend.ts

@@ -1,5 +1,10 @@
+import type { EnvMapping } from "@/lib/env-mapping";
 import type { AppDefinition } from "./types";
 
+const resendEnvMappings: EnvMapping[] = [
+  { envName: "RESEND_API_KEY", placeholder: "humr:sentinel" },
+];
+
 export const resend: AppDefinition = {
   id: "resend",
   name: "Resend",
@@ -18,4 +23,5 @@ export const resend: AppDefinition = {
     ],
   },
   available: true,
+  envMappings: resendEnvMappings,
 };

apps/web/src/lib/apps/spotify.ts

@@ -1,5 +1,10 @@
+import type { EnvMapping } from "@/lib/env-mapping";
 import type { AppDefinition } from "./types";
 
+const spotifyEnvMappings: EnvMapping[] = [
+  { envName: "SPOTIFY_ACCESS_TOKEN", placeholder: "humr:sentinel" },
+];
+
 export const spotify: AppDefinition = {
   id: "spotify",
   name: "Spotify",
@@ -193,4 +198,5 @@ export const spotify: AppDefinition = {
       clientSecret: "SPOTIFY_CLIENT_SECRET",
     },
   },
+  envMappings: spotifyEnvMappings,
 };

apps/web/src/lib/apps/types.ts

@@ -83,7 +83,10 @@ export interface AppDefinition {
   };
   /**
    * Env vars a consumer should inject into any agent granted this connection.
-   * Omitted for apps with no known CLI integration.
+   * Required — every app must declare the env contract its CLI/SDK consumers
+   * expect so agents can call the provider without per-provider wiring. Apps
+   * in the same OAuth family can share an exported mapping (see
+   * `googleWorkspaceEnvMappings`, `githubEnvMappings`).
    */
-  envMappings?: EnvMapping[];
+  envMappings: EnvMapping[];
 }

apps/web/src/lib/apps/youtube.ts

@@ -4,6 +4,7 @@ import {
   exchangeGoogleCode,
   googleConfigFields,
   googleEnvDefaults,
+  googleWorkspaceEnvMappings,
 } from "./google-oauth";
 
 export const youtube: AppDefinition = {
@@ -48,4 +49,5 @@ export const youtube: AppDefinition = {
     fields: googleConfigFields,
     envDefaults: googleEnvDefaults,
   },
+  envMappings: googleWorkspaceEnvMappings,
 };