Skip to main content

moonlit_pdk_macros/
lib.rs

1//! `moonlit_plugin!` — generates the WIT `Guest` glue and `export!` for a
2//! plugin from a declaration of its name, middlewares, and optional config/state.
3//!
4//! Emits plugin ABI `moonlit:plugin@0.3.0` metadata: an optional embedded icon
5//! (`icon = "…"`) and, per middleware, a JSON Schema for both its typed `Input`
6//! and its `Output`.
7
8use base64::Engine as _;
9use proc_macro::TokenStream;
10use quote::quote;
11use syn::parse::{Parse, ParseStream};
12use syn::{Ident, LitStr, Token, Type, braced, bracketed};
13
14/// `moonlit_plugin! { name: "git", icon: "icon.png", config: C, middlewares: [A, B], state: S }`
15struct PluginDecl {
16  name: LitStr,
17  /// Path to a PNG/WebP icon, relative to the author crate's `CARGO_MANIFEST_DIR`.
18  icon: Option<LitStr>,
19  config: Option<Type>,
20  middlewares: Vec<Type>,
21  state: Option<Type>,
22}
23
24impl Parse for PluginDecl {
25  fn parse(input: ParseStream) -> syn::Result<Self> {
26    let mut name: Option<LitStr> = None;
27    let mut icon: Option<LitStr> = None;
28    let mut config: Option<Type> = None;
29    let mut middlewares: Option<Vec<Type>> = None;
30    let mut state: Option<Type> = None;
31
32    while !input.is_empty() {
33      let key: Ident = input.parse()?;
34      input.parse::<Token![:]>()?;
35      match key.to_string().as_str() {
36        "name" => name = Some(input.parse()?),
37        "icon" => icon = Some(input.parse()?),
38        "config" => config = Some(input.parse()?),
39        "state" => state = Some(input.parse()?),
40        "middlewares" => {
41          let content;
42          bracketed!(content in input);
43          let types = content.parse_terminated(Type::parse, Token![,])?;
44          middlewares = Some(types.into_iter().collect());
45        }
46        other => {
47          return Err(syn::Error::new(
48            key.span(),
49            format!("unknown moonlit_plugin! field `{other}` (expected name, icon, config, middlewares, state)"),
50          ));
51        }
52      }
53      // optional trailing comma between fields
54      let _ = input.parse::<Token![,]>();
55    }
56
57    Ok(PluginDecl {
58      name: name.ok_or_else(|| input.error("missing `name:`"))?,
59      icon,
60      config,
61      middlewares: middlewares.ok_or_else(|| input.error("missing `middlewares:`"))?,
62      state,
63    })
64  }
65}
66
67/// Read the icon at expansion time and build a `data:` URI expression for
68/// `plugin-metadata.icon`. MIME comes from the extension; unknown extensions are
69/// a compile error. The emitted `include_bytes!` is inert (discarded) but makes
70/// `rustc` track the file so a changed icon triggers a rebuild.
71#[must_use]
72fn icon_expr(icon: Option<&LitStr>) -> proc_macro2::TokenStream {
73  let Some(lit) = icon else {
74    return quote! { ::core::option::Option::None };
75  };
76  let rel = lit.value();
77  let extension = std::path::Path::new(&rel).extension().and_then(std::ffi::OsStr::to_str);
78  let mime = if extension == Some("png") {
79    "image/png"
80  } else if extension == Some("webp") {
81    "image/webp"
82  } else {
83    return syn::Error::new(lit.span(), "icon must be a .png or .webp file").to_compile_error();
84  };
85  let Ok(manifest_dir) = std::env::var("CARGO_MANIFEST_DIR") else {
86    return syn::Error::new(lit.span(), "CARGO_MANIFEST_DIR unavailable; cannot locate icon").to_compile_error();
87  };
88  let path = std::path::Path::new(&manifest_dir).join(&rel);
89  let bytes = match std::fs::read(&path) {
90    Ok(b) => b,
91    Err(e) => {
92      return syn::Error::new(lit.span(), format!("cannot read icon `{}`: {e}", path.display())).to_compile_error();
93    }
94  };
95  let b64 = base64::engine::general_purpose::STANDARD.encode(&bytes);
96  let data_uri = format!("data:{mime};base64,{b64}");
97  quote! {
98      {
99          // Rebuild tracking only — the encoded string above is the real value.
100          const _: &[u8] =
101              ::core::include_bytes!(::core::concat!(::core::env!("CARGO_MANIFEST_DIR"), "/", #rel));
102          ::core::option::Option::Some(::std::string::String::from(#data_uri))
103      }
104  }
105}
106
107#[proc_macro]
108pub fn moonlit_plugin(input: TokenStream) -> TokenStream {
109  // Allow trailing braces form `moonlit_plugin! { ... }`.
110  let decl = syn::parse_macro_input!(input as PluginDeclInput).0;
111  expand(&decl).into()
112}
113
114/// Wrapper so the macro accepts either `{ ... }` or bare `...`.
115struct PluginDeclInput(PluginDecl);
116impl Parse for PluginDeclInput {
117  fn parse(input: ParseStream) -> syn::Result<Self> {
118    if input.peek(syn::token::Brace) {
119      let content;
120      braced!(content in input);
121      Ok(PluginDeclInput(content.parse()?))
122    } else {
123      Ok(PluginDeclInput(input.parse()?))
124    }
125  }
126}
127
128#[must_use]
129fn expand(decl: &PluginDecl) -> proc_macro2::TokenStream {
130  let name = &decl.name;
131  let list_entries = list_entries(&decl.middlewares);
132  let icon = icon_expr(decl.icon.as_ref());
133  let exec_arms = exec_arms(&decl.middlewares);
134  let (state_static, state_attach) = state_tokens(decl.state.as_ref());
135  let (config_static, config_init, config_attach) = config_tokens(decl.config.as_ref());
136
137  quote! {
138      #[derive(::core::default::Default)]
139      struct MoonlitComponent;
140
141      #state_static
142      #config_static
143
144      impl ::moonlit_pdk::bindings::Guest for MoonlitComponent {
145          fn describe() -> ::moonlit_pdk::bindings::PluginMetadata {
146              ::moonlit_pdk::bindings::PluginMetadata {
147                  name: #name.to_string(),
148                  version: ::core::env!("CARGO_PKG_VERSION").to_string(),
149                  description: ::core::option_env!("CARGO_PKG_DESCRIPTION")
150                      .unwrap_or("").to_string(),
151                  icon: #icon,
152              }
153          }
154
155          fn init(
156              plugin_config: ::std::string::String,
157          ) -> ::core::result::Result<
158              ::moonlit_pdk::bindings::PluginMetadata,
159              ::std::string::String,
160          > {
161              #config_init
162              ::core::result::Result::Ok(<Self as ::moonlit_pdk::bindings::Guest>::describe())
163          }
164
165          fn list_middlewares(
166          ) -> ::std::vec::Vec<::moonlit_pdk::bindings::MiddlewareInfo> {
167              ::std::vec![ #(#list_entries),* ]
168          }
169
170          fn execute(
171              middleware: ::std::string::String,
172              ctx: ::moonlit_pdk::bindings::ReleaseContext,
173              config: ::std::string::String,
174          ) -> ::moonlit_pdk::bindings::MiddlewareResult {
175              #[cfg(target_arch = "wasm32")]
176              let host = ::moonlit_pdk::RealHost;
177              #[cfg(not(target_arch = "wasm32"))]
178              let host = __MoonlitUnavailableHost;
179              let ctx = ::moonlit_pdk::Context::new(
180                  &host,
181                  ctx.working_directory,
182                  ctx.step_name,
183              );
184              #state_attach
185              #config_attach
186              match middleware.as_str() {
187                  #(#exec_arms)*
188                  other => ::moonlit_pdk::MiddlewareResult::<()>::failure(
189                      ::std::format!("unknown middleware: {}", other)
190                  ).into_wit(),
191              }
192          }
193      }
194
195      // Off-wasm the component entry points are never invoked, but the code
196      // must still type-check. This host is only constructed on non-wasm and
197      // never called (the exported fns run only inside the component).
198      #[cfg(not(target_arch = "wasm32"))]
199      struct __MoonlitUnavailableHost;
200      #[cfg(not(target_arch = "wasm32"))]
201      impl ::moonlit_pdk::Host for __MoonlitUnavailableHost {
202          fn log(&self, _l: ::moonlit_pdk::LogLevel, _m: &str) {}
203          fn get_config(&self, _p: &str) -> ::core::option::Option<::std::string::String> { None }
204          fn report_progress(&self, _m: &str) {}
205          fn process_run(&self, _cmd: &::moonlit_pdk::process::ProcessCommand) -> ::core::result::Result<::moonlit_pdk::process::ProcessOutput, ::std::string::String> { Err("process unavailable".to_string()) }
206          fn process_spawn(&self, _cmd: &::moonlit_pdk::process::ProcessCommand) -> ::core::result::Result<::std::boxed::Box<dyn ::moonlit_pdk::process::ChildHandle>, ::std::string::String> { Err("process unavailable".to_string()) }
207          fn http_send(&self, _req: &::moonlit_pdk::http::HttpRequestData) -> ::core::result::Result<::moonlit_pdk::http::HttpResponseData, ::std::string::String> { Err("http unavailable".to_string()) }
208          fn env_var(&self, _n: &str) -> ::core::option::Option<::std::string::String> { None }
209          fn env_vars(&self) -> ::std::vec::Vec<(::std::string::String, ::std::string::String)> { ::std::vec::Vec::new() }
210          fn random_bytes(&self, n: usize) -> ::std::vec::Vec<u8> { ::std::vec![0u8; n] }
211          fn monotonic_nanos(&self) -> u64 { 0 }
212          fn sleep_nanos(&self, _nanos: u64) {}
213      }
214
215      ::moonlit_pdk::export!(MoonlitComponent with_types_in ::moonlit_pdk::bindings);
216  }
217}
218
219#[must_use]
220fn list_entries(mws: &[Type]) -> Vec<proc_macro2::TokenStream> {
221  // list-middlewares entries; input-schema / output-schema are the JSON Schemas
222  // of each middleware's `Input` / `Output` (draft 2020-12), via the SDK helper.
223  mws
224    .iter()
225    .map(|m| {
226      quote! {
227          ::moonlit_pdk::bindings::MiddlewareInfo {
228              name: <#m as ::moonlit_pdk::Middleware>::NAME.to_string(),
229              description: <#m as ::moonlit_pdk::Middleware>::DESCRIPTION.to_string(),
230              input_schema: ::core::option::Option::Some(
231                  ::moonlit_pdk::__schema_json::<<#m as ::moonlit_pdk::Middleware>::Input>()
232              ),
233              output_schema: ::core::option::Option::Some(
234                  ::moonlit_pdk::__schema_json::<<#m as ::moonlit_pdk::Middleware>::Output>()
235              ),
236          }
237      }
238    })
239    .collect()
240}
241
242#[must_use]
243fn exec_arms(mws: &[Type]) -> Vec<proc_macro2::TokenStream> {
244  // execute dispatch arms
245  mws
246    .iter()
247    .map(|m| {
248      quote! {
249          <#m as ::moonlit_pdk::Middleware>::NAME => {
250              let input: <#m as ::moonlit_pdk::Middleware>::Input =
251                  match ::moonlit_pdk::config::from_json_value(&config) {
252                      Ok(c) => c,
253                      Err(e) => {
254                          return ::moonlit_pdk::MiddlewareResult::<
255                              <#m as ::moonlit_pdk::Middleware>::Output,
256                          >::failure(
257                              ::std::format!("invalid input for `{}`: {}", middleware, e)
258                          ).into_wit();
259                      }
260                  };
261              let mw = <#m as ::core::default::Default>::default();
262              ::moonlit_pdk::Middleware::execute(&mw, &ctx, input).into_wit()
263          }
264      }
265    })
266    .collect()
267}
268
269#[must_use]
270fn state_tokens(state: Option<&Type>) -> (proc_macro2::TokenStream, proc_macro2::TokenStream) {
271  // optional state static + install
272  match state {
273    Some(ty) => (
274      quote! {
275          static __MOONLIT_STATE: ::std::sync::OnceLock<#ty> = ::std::sync::OnceLock::new();
276          fn __moonlit_state() -> &'static #ty {
277              __MOONLIT_STATE.get_or_init(<#ty as ::core::default::Default>::default)
278          }
279      },
280      quote! { let ctx = ctx.with_state(__moonlit_state()); },
281    ),
282    None => (quote! {}, quote! {}),
283  }
284}
285
286#[must_use]
287fn config_tokens(config: Option<&Type>) -> (proc_macro2::TokenStream, proc_macro2::TokenStream, proc_macro2::TokenStream) {
288  // optional plugin-config: validated at init, stored, attached to ctx
289  match config {
290    Some(ty) => (
291      quote! {
292          static __MOONLIT_PLUGIN_CONFIG: ::std::sync::OnceLock<#ty> = ::std::sync::OnceLock::new();
293          fn __moonlit_plugin_config() -> ::core::option::Option<&'static #ty> {
294              __MOONLIT_PLUGIN_CONFIG.get()
295          }
296      },
297      quote! {
298          let parsed: #ty = ::moonlit_pdk::config::from_json_value(&plugin_config)
299              .map_err(|e| ::std::format!("invalid plugin config: {}", e))?;
300          ::moonlit_pdk::PluginConfig::validate(&parsed)?;
301          let _ = __MOONLIT_PLUGIN_CONFIG.set(parsed);
302      },
303      quote! {
304          let ctx = match __moonlit_plugin_config() {
305              Some(c) => ctx.with_plugin_config(c),
306              None => ctx,
307          };
308      },
309    ),
310    None => (quote! {}, quote! {}, quote! {}),
311  }
312}
313
314#[cfg(test)]
315mod tests {
316  use super::*;
317  use proc_macro2::Span;
318
319  fn parse_error(tokens: proc_macro2::TokenStream) -> String {
320    syn::parse2::<PluginDecl>(tokens)
321      .err()
322      .expect("declaration must be rejected")
323      .to_string()
324  }
325
326  fn icon(path: &str) -> String {
327    icon_expr(Some(&LitStr::new(path, Span::call_site()))).to_string()
328  }
329
330  #[test]
331  fn unknown_field_is_rejected_with_the_expected_list() {
332    let message = parse_error(quote! { name: "p", bogus: "x" });
333    assert!(message.contains("unknown moonlit_plugin! field `bogus`"), "got: {message}");
334  }
335
336  #[test]
337  fn name_and_middlewares_are_required() {
338    assert!(parse_error(quote! { middlewares: [A] }).contains("missing `name:`"));
339    assert!(parse_error(quote! { name: "p" }).contains("missing `middlewares:`"));
340  }
341
342  #[test]
343  fn braced_and_bare_declarations_parse_the_same_fields() {
344    let braced = syn::parse2::<PluginDeclInput>(quote! { { name: "p", config: C, middlewares: [A, B], state: S } })
345      .expect("braced form parses")
346      .0;
347    let bare = syn::parse2::<PluginDeclInput>(quote! { name: "p" middlewares: [A] })
348      .expect("bare form parses")
349      .0;
350    assert_eq!(braced.name.value(), "p");
351    assert_eq!(braced.middlewares.len(), 2);
352    assert!(braced.config.is_some() && braced.state.is_some());
353    assert_eq!(bare.middlewares.len(), 1);
354    assert!(bare.icon.is_none());
355  }
356
357  #[test]
358  fn missing_icon_expands_to_none() {
359    assert!(icon_expr(None).to_string().contains("None"));
360  }
361
362  #[test]
363  fn webp_icon_becomes_a_webp_data_uri() {
364    let path = std::env::temp_dir().join(format!("moonlit-pdk-macros-{}.webp", std::process::id()));
365    std::fs::write(&path, b"RIFF").unwrap();
366    let expanded = icon(&path.display().to_string());
367    std::fs::remove_file(&path).unwrap();
368    assert!(expanded.contains("data:image/webp;base64,UklGRg=="), "got: {expanded}");
369  }
370
371  #[test]
372  fn unsupported_icon_extension_is_a_compile_error() {
373    assert!(icon("icon.gif").contains("icon must be a .png or .webp file"));
374    assert!(icon("icon").contains("icon must be a .png or .webp file"));
375  }
376
377  #[test]
378  fn unreadable_icon_is_a_compile_error() {
379    let missing = std::env::temp_dir().join("moonlit-pdk-macros-missing-icon.png");
380    assert!(icon(&missing.display().to_string()).contains("cannot read icon"));
381  }
382}