feat(cli): generate sdk_glue.rs with sdk_client() + block_on() for custom commands (#16311)

Author: jsklan

generators/cli/changes/unreleased/sdk-client-glue.yml

@@ -0,0 +1,7 @@
+- summary: |
+    Generate `sdk_glue.rs` module providing `sdk_client()` and `block_on()`
+    helpers that bridge the CLI's AppContext to the co-generated SDK client.
+    Custom command handlers can now use typed SDK calls without manual
+    Cargo.toml edits — the SDK crate is the sole direct dependency and
+    re-exports all types.
+  type: feat

generators/cli/src/copySpecs.ts

@@ -66,8 +66,10 @@ export async function copySpecs(args: {
     specsDir?: string;
     /** When true, emit `mod custom;` + `custom::register(app)` in main.rs. */
     embedTypes?: boolean;
+    /** When true, emit `mod sdk_glue;` in main.rs for the SDK bridge. */
+    embedSdk?: boolean;
 }): Promise<void> {
-    const { outputDir, binaryName, authBindings, specsDir, embedTypes } = args;
+    const { outputDir, binaryName, authBindings, specsDir, embedTypes, embedSdk } = args;
     const manifest = await readSpecsManifest(specsDir);
     if (manifest == null) {
         return;
@@ -90,12 +92,18 @@ export async function copySpecs(args: {
 
     await writeFile(
         path.join(binDir, "main.rs"),
-        renderMainRs({ binaryName, entries, authBindings, embedTypes: embedTypes ?? false })
+        renderMainRs({
+            binaryName,
+            entries,
+            authBindings,
+            embedTypes: embedTypes ?? false,
+            embedSdk: embedSdk ?? false
+        })
     );
 
     // Scaffold custom.rs for user-authored command handlers.
     if (embedTypes === true) {
-        await scaffoldCustomRs(binDir, binaryName);
+        await scaffoldCustomRs(binDir, binaryName, embedSdk ?? false);
     }
 }
 
@@ -109,7 +117,7 @@ interface SpecEntry {
  * own async command handlers. Listed in `.fernignore` so `fern generate`
  * never overwrites user changes.
  */
-async function scaffoldCustomRs(binDir: string, binaryName: string): Promise<void> {
+async function scaffoldCustomRs(binDir: string, binaryName: string, embedSdk: boolean): Promise<void> {
     const customRsPath = path.join(binDir, "custom.rs");
     // Only create if it doesn't already exist (respects .fernignore).
     try {
@@ -118,27 +126,75 @@ async function scaffoldCustomRs(binDir: string, binaryName: string): Promise<voi
     } catch (_e: unknown) {
         // does not exist — scaffold it below
     }
-    const typesCrate = `${binaryName.replace(/-/g, "_")}_types`;
     const sdkCrate = `${binaryName.replace(/-/g, "_")}_sdk`;
-    const content = [
+    const content = embedSdk ? renderCustomRsWithSdk(sdkCrate) : renderCustomRsTypesOnly(binaryName);
+    await writeFile(customRsPath, content);
+}
+
+/** Scaffold when the SDK crate is available (default). */
+function renderCustomRsWithSdk(sdkCrate: string): string {
+    return [
+        "//! Custom command handlers.",
+        "//!",
+        "//! This file is yours to edit — add it to `.fernignore` so",
+        "//! `fern generate` will never overwrite your changes.",
+        "//!",
+        "//! The generated `main.rs` calls `custom::register(app)` at",
+        "//! startup, composing your commands into the CLI at compile time.",
+        "//!",
+        "//! Each handler receives an `AppContext`. Use `sdk_glue::sdk_client(ctx)`",
+        "//! to get a fully-wired SDK client that inherits the CLI's auth,",
+        "//! retries, TLS, and global headers. Use `sdk_glue::block_on(future)`",
+        "//! to run async SDK calls from synchronous handler context.",
+        `//! Types are available via \`${sdkCrate}::api::*\`.`,
+        "",
+        "use fern_cli_sdk::app::CliApp;",
+        "",
+        "/// Register custom commands on the CLI app builder.",
+        "///",
+        "/// Called from `main.rs` during startup. Uncomment the example",
+        "/// below and adapt it to your API to get started.",
+        "pub fn register(app: CliApp) -> CliApp {",
+        "    // Example: typed SDK client usage with the co-generated SDK.",
+        "    //",
+        `    // use ${sdkCrate}::api::*;`,
+        "    //",
+        "    // let app = app.command(",
+        '    //     clap::Command::new("get-plant")',
+        '    //         .about("Fetch a plant by its ID")',
+        '    //         .arg(clap::Arg::new("plant-id").required(true)),',
+        "    //     |matches, ctx| {",
+        '    //         let plant_id = matches.get_one::<String>("plant-id").unwrap();',
+        "    //         let client = super::sdk_glue::sdk_client(ctx);",
+        "    //         let plant = super::sdk_glue::block_on(",
+        "    //             client.plants.get_plant(plant_id, None),",
+        "    //         )?;",
+        '    //         println!("{}", serde_json::to_string_pretty(&plant).unwrap());',
+        "    //         Ok(())",
+        "    //     },",
+        "    // );",
+        "    app",
+        "}",
+        ""
+    ].join("\n");
+}
+
+/** Scaffold when only the types crate is available (embedSdk: false). */
+function renderCustomRsTypesOnly(binaryName: string): string {
+    const typesCrate = `${binaryName.replace(/-/g, "_")}_types`;
+    return [
         "//! Custom command handlers.",
         "//!",
         "//! This file is yours to edit — add it to `.fernignore` so",
         "//! `fern generate` will never overwrite your changes.",
         "//!",
         "//! The generated `main.rs` calls `custom::register(app)` at",
         "//! startup, composing your commands into the CLI at compile time.",
-        "//! This is the same pattern used by other Fern generators (e.g.",
-        "//! Ruby's `requirePaths`) — the generated entrypoint references",
-        "//! this user-owned file, and `.fernignore` keeps it safe across",
-        "//! regenerations.",
         "//!",
         "//! Each handler receives an `AppContext` whose `invoke()` and",
         "//! `execute()` methods use the CLI's native HTTP executor.",
         `//! Combine these with the typed structs from \`${typesCrate}\``,
         "//! for strongly-typed request/response serialization.",
-        `//! The SDK crate (\`${sdkCrate}\`) provides typed client helpers`,
-        "//! via `ctx.sdk_client()` (available once the runtime handle lands).",
         "",
         "use fern_cli_sdk::app::CliApp;",
         "",
@@ -172,24 +228,20 @@ async function scaffoldCustomRs(binDir: string, binaryName: string): Promise<voi
         "    //         Ok(())",
         "    //     },",
         "    // );",
-        "    //",
-        "    // SDK client usage (available after the runtime handle lands):",
-        `    // use ${sdkCrate}::prelude::*;`,
-        "    // let client = ctx.sdk_client();",
         "    app",
         "}",
         ""
     ].join("\n");
-    await writeFile(customRsPath, content);
 }
 
 function renderMainRs(args: {
     binaryName: string;
     entries: SpecEntry[];
     authBindings: DetectedAuthBinding[];
     embedTypes: boolean;
+    embedSdk: boolean;
 }): string {
-    const { binaryName, entries, authBindings, embedTypes } = args;
+    const { binaryName, entries, authBindings, embedTypes, embedSdk } = args;
 
     // Separate root-level auth (typed builders) from binding-level auth
     const rootAuthBindings = authBindings.filter((b) => b.placement === "root");
@@ -217,6 +269,9 @@ function renderMainRs(args: {
 
     if (embedTypes) {
         lines.push("mod custom;");
+        if (embedSdk) {
+            lines.push("mod sdk_glue;");
+        }
         lines.push("");
     }
 

generators/cli/src/generateSdkGlue.ts

@@ -0,0 +1,206 @@
+/**
+ * Generate `cli/<binaryName>/sdk_glue.rs` — the adapter that bridges
+ * the CLI's runtime (`AppContext`, `CliExecutor`) to the co-generated
+ * SDK crate's typed client.
+ *
+ * Provides two public helpers for custom command handlers:
+ *
+ *   - `sdk_client(ctx)` — construct a fully-wired SDK root client that
+ *     routes through the CLI's auth/retry/TLS stack.
+ *   - `block_on(future)` — run an async SDK call from synchronous
+ *     handler context (bridges `ApiError` → `CliError`).
+ *
+ * The generated code reads the SDK crate's `src/api/resources/mod.rs`
+ * to discover the root client struct and its sub-client fields, so the
+ * construction code is always in sync with the generated SDK.
+ */
+
+import { readFile, writeFile } from "fs/promises";
+import path from "path";
+
+/** A sub-client field parsed from the root client struct. */
+interface SubClientField {
+    fieldName: string;
+    typeName: string;
+}
+
+/** Root client info parsed from the generated SDK. */
+interface RootClientInfo {
+    name: string;
+    subClients: SubClientField[];
+}
+
+/**
+ * Parse `src/api/resources/mod.rs` to extract the root client struct
+ * definition and its sub-client fields.
+ *
+ * Expected pattern:
+ * ```rust
+ * pub struct ApiClient {
+ *     pub config: ClientConfig,
+ *     pub pets: PetsClient,
+ *     pub auth: AuthClient,
+ * }
+ * ```
+ */
+function parseRootClient(modRsContent: string): RootClientInfo {
+    const structMatch = modRsContent.match(/pub struct (\w+Client)\s*\{([^}]+)\}/);
+    if (structMatch == null) {
+        throw new Error("Could not find root client struct in SDK's api/resources/mod.rs");
+    }
+
+    const name = structMatch[1] ?? "";
+    const body = structMatch[2] ?? "";
+    const subClients: SubClientField[] = [];
+
+    // Match each `pub <field>: <Type>,` line, skipping `config: ClientConfig`
+    const fieldRegex = /pub\s+(\w+)\s*:\s*(\w+)\s*,?/g;
+    let match;
+    while ((match = fieldRegex.exec(body)) !== null) {
+        const fieldName = match[1] ?? "";
+        const typeName = match[2] ?? "";
+        if (typeName === "ClientConfig") {
+            continue; // skip the config field
+        }
+        subClients.push({ fieldName, typeName });
+    }
+
+    return { name, subClients };
+}
+
+/**
+ * Generate the `sdk_glue.rs` module content.
+ */
+function renderSdkGlue(sdkCrateSnake: string, rootClient: RootClientInfo): string {
+    const subClientInits = rootClient.subClients
+        .map(
+            (sc) =>
+                `        ${sc.fieldName}: ${sdkCrateSnake}::api::${sc.typeName} { http_client: http_client.clone() },`
+        )
+        .join("\n");
+
+    return `\
+//! Generated SDK client glue — bridges AppContext to the co-generated SDK.
+//!
+//! Auto-generated by @fern-api/cli-generator. Do not edit by hand.
+
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+
+use fern_cli_sdk::error::CliError;
+use fern_cli_sdk::openapi::AppContext;
+use fern_cli_sdk::sdk_executor::{CliExecutor, SdkRequestExecutor};
+
+// ---------------------------------------------------------------------------
+// Executor adapter: CliExecutor → SDK RequestExecutor
+// ---------------------------------------------------------------------------
+
+struct CliExecutorAdapter(Arc<CliExecutor>);
+
+impl ${sdkCrateSnake}::RequestExecutor for CliExecutorAdapter {
+    fn execute(
+        &self,
+        request: reqwest::Request,
+    ) -> Pin<Box<dyn Future<Output = Result<reqwest::Response, reqwest::Error>> + Send + '_>> {
+        SdkRequestExecutor::execute(&*self.0, request)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// sdk_client — construct a fully-wired SDK root client
+// ---------------------------------------------------------------------------
+
+/// Build the SDK root client from the CLI's runtime context.
+///
+/// The returned client routes all HTTP through the CLI's executor, so
+/// it inherits auth, retries, TLS, and global headers automatically.
+pub fn sdk_client(ctx: &AppContext) -> ${sdkCrateSnake}::api::${rootClient.name} {
+    let executor = ctx.build_sdk_executor();
+    let adapter = Arc::new(CliExecutorAdapter(executor));
+    let config = ${sdkCrateSnake}::ClientConfig::default();
+    let http_client = ${sdkCrateSnake}::HttpClient::with_executor(
+        adapter as Arc<dyn ${sdkCrateSnake}::RequestExecutor>,
+        config.clone(),
+    );
+    ${sdkCrateSnake}::api::${rootClient.name} {
+        config,
+${subClientInits}
+    }
+}
+
+// ---------------------------------------------------------------------------
+// block_on — async SDK call → sync handler result
+// ---------------------------------------------------------------------------
+
+/// Execute an async SDK operation from a synchronous custom-command handler.
+///
+/// Bridges the SDK's \`ApiError\` into the CLI's \`CliError\` so \`?\` works
+/// naturally in handler bodies.
+pub fn block_on<F, T>(future: F) -> Result<T, CliError>
+where
+    F: Future<Output = Result<T, ${sdkCrateSnake}::ApiError>>,
+{
+    tokio::task::block_in_place(|| {
+        let handle = tokio::runtime::Handle::current();
+        handle.block_on(future).map_err(convert_api_error)
+    })
+}
+
+fn convert_api_error(e: ${sdkCrateSnake}::ApiError) -> CliError {
+    match e {
+        ${sdkCrateSnake}::ApiError::Http { status, message } => CliError::Api {
+            code: status,
+            message,
+            reason: http_status_reason(status).to_string(),
+        },
+        ${sdkCrateSnake}::ApiError::Network(err) => {
+            CliError::Other(anyhow::anyhow!("SDK network error: {err}"))
+        }
+        other => CliError::Other(anyhow::anyhow!("SDK error: {other}")),
+    }
+}
+
+fn http_status_reason(status: u16) -> &'static str {
+    match status {
+        400 => "badRequest",
+        401 => "unauthorized",
+        403 => "forbidden",
+        404 => "notFound",
+        408 => "requestTimeout",
+        409 => "conflict",
+        429 => "tooManyRequests",
+        500 => "internalServerError",
+        502 => "badGateway",
+        503 => "serviceUnavailable",
+        504 => "gatewayTimeout",
+        _ => "httpError",
+    }
+}
+`;
+}
+
+/**
+ * Generate `cli/<binaryName>/sdk_glue.rs`.
+ *
+ * Must be called AFTER `generateEmbeddedSdk` so the SDK crate's source
+ * files are on disk.
+ */
+export async function generateSdkGlue(args: {
+    outputDir: string;
+    binaryName: string;
+    sdkCrateName: string;
+}): Promise<void> {
+    const { outputDir, binaryName, sdkCrateName } = args;
+    const sdkCrateSnake = sdkCrateName.replace(/-/g, "_");
+
+    // Read the SDK's root client definition.
+    const modRsPath = path.join(outputDir, sdkCrateName, "src", "api", "resources", "mod.rs");
+    const modRsContent = await readFile(modRsPath, "utf-8");
+    const rootClient = parseRootClient(modRsContent);
+
+    // Write the glue module.
+    const binDir = path.join(outputDir, "cli", binaryName);
+    const content = renderSdkGlue(sdkCrateSnake, rootClient);
+    await writeFile(path.join(binDir, "sdk_glue.rs"), content);
+}