fix: use oxfmt for generated toml

Author: Goldziher

CHANGELOG.md

@@ -40,6 +40,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **alef-cli/alef-e2e: use `oxfmt` instead of Taplo for generated TOML normalization**:
+  the default post-generation formatters now call `pnpm dlx oxfmt` for WASM
+  manifests, FFI/workspace formatting, and Rust e2e `Cargo.toml` normalization,
+  aligning generated output with Kreuzberg's shared pre-commit hooks.
+  (`crates/alef-cli/src/pipeline/format.rs`, `crates/alef-e2e/src/format.rs`)
+
+- **alef-backend-ffi: escape generated `cbindgen.toml` `after_includes` safely**:
+  Doxygen blocks embedded in `after_includes` now render as escaped TOML
+  multiline strings, so backslash commands such as `\code` and rustdoc examples
+  containing triple quotes no longer make `cbindgen.toml` invalid.
+  (`crates/alef-backend-ffi/templates/cbindgen_toml.jinja`,
+  `crates/alef-backend-ffi/src/gen_bindings/helpers.rs`,
+  `crates/alef-backend-ffi/src/gen_bindings/mod.rs`)
+
 - **alef-backend-wasm: emit current `getrandom` for wasm target dependencies**:
   generated WASM `Cargo.toml` files now use `getrandom` `0.4` with `wasm_js`, so downstream
   aggressive dependency upgrades no longer make generated manifests stale.

crates/alef-backend-ffi/src/gen_bindings/helpers.rs

@@ -393,16 +393,30 @@ pub(super) fn gen_cbindgen_toml(prefix: &str, api: &alef_core::ir::ApiSurface) -
         })
         .collect::<Vec<_>>()
         .join("\n");
+    let after_includes = if forward_decls.is_empty() {
+        String::new()
+    } else {
+        toml_multiline_basic_string(&format!("/* Opaque type forward declarations */\n{forward_decls}\n"))
+    };
 
     crate::template_env::render(
         "cbindgen_toml.jinja",
         minijinja::context! {
             prefix_upper => &prefix_upper,
-            forward_decls => &forward_decls,
+            after_includes => &after_includes,
         },
     )
 }
 
+fn toml_multiline_basic_string(value: &str) -> String {
+    let escaped = value
+        .replace('\\', "\\\\")
+        .replace("\"\"\"", "\\\"\\\"\\\"")
+        .replace('\u{8}', "\\b")
+        .replace('\u{c}', "\\f");
+    format!("\"\"\"\n{escaped}\"\"\"")
+}
+
 // ---------------------------------------------------------------------------
 // build.rs generation
 // ---------------------------------------------------------------------------

crates/alef-backend-ffi/src/gen_bindings/mod.rs

@@ -1583,6 +1583,7 @@ sources = ["src/lib.rs"]
 
         let files = backend.generate_bindings(&api, &config).unwrap();
         let cbindgen = files.iter().find(|f| f.path.ends_with("cbindgen.toml")).unwrap();
+        toml::from_str::<toml::Value>(&cbindgen.content).expect("cbindgen.toml must be valid TOML");
 
         // Doxygen block precedes the typedef in `forward_decls`. The doc text
         // is lifted from `TypeDef.doc` and rendered as `/** * ... */`.
@@ -1605,6 +1606,38 @@ sources = ["src/lib.rs"]
         );
     }
 
+    #[test]
+    fn test_cbindgen_toml_escapes_doxygen_backslashes() {
+        let mut api = doxygen_sample_api();
+        api.types[0].doc = r##"Has an example.
+
+# Example
+
+```rust
+let value = "triple """ quote";
+```"##
+            .to_string();
+        let config = sample_config();
+        let backend = FfiBackend;
+
+        let files = backend.generate_bindings(&api, &config).unwrap();
+        let cbindgen = files.iter().find(|f| f.path.ends_with("cbindgen.toml")).unwrap();
+        let parsed = toml::from_str::<toml::Value>(&cbindgen.content).expect("cbindgen.toml must parse");
+        let after_includes = parsed
+            .get("after_includes")
+            .and_then(toml::Value::as_str)
+            .expect("after_includes must be a string");
+
+        assert!(
+            after_includes.contains("\\code") && after_includes.contains("\\endcode"),
+            "Doxygen markers must survive TOML parsing: {after_includes}"
+        );
+        assert!(
+            after_includes.contains("triple \"\"\" quote"),
+            "triple quotes must round-trip through TOML parsing: {after_includes}"
+        );
+    }
+
     #[test]
     fn test_enum_opaque_typedef_carries_doxygen_block() {
         let api = doxygen_sample_api();

crates/alef-backend-ffi/templates/cbindgen_toml.jinja

@@ -3,11 +3,8 @@ language = "C"
 include_guard = "{{ prefix_upper }}_H"
 pragma_once = true
 autogen_warning = "/* This file is auto-generated by alef. DO NOT EDIT. */"
-{% if forward_decls %}
-after_includes = """
-/* Opaque type forward declarations */
-{{ forward_decls }}
-"""
+{% if after_includes %}
+after_includes = {{ after_includes }}
 {% endif %}
 [defines]
 "target_os = windows" = "SKIF_WINDOWS"

crates/alef-cli/src/pipeline/format.rs

@@ -139,9 +139,8 @@ fn get_default_formatter(config: &ResolvedCrateConfig, lang: Language) -> Option
         // `cargo sort` normalises the generated Cargo.toml so prek's cargo-sort hook
         // is a no-op; without it, cargo-sort reformats feature indentation after the
         // hash is finalised, making alef verify report the file as stale.
-        // `taplo fmt` then re-flows array/inline-table whitespace per the consumer's
-        // `.taplo.toml` so prek's taplo hook is likewise a no-op (best-effort: missing
-        // taplo is skipped silently via `is_tool_available`).
+        // `oxfmt` then re-flows array/inline-table whitespace consistently with
+        // the shared Kreuzberg pre-commit hook.
         Language::Wasm => {
             let crate_dir = config
                 .output_for("wasm")
@@ -160,8 +159,8 @@ fn get_default_formatter(config: &ResolvedCrateConfig, lang: Language) -> Option
                         args: vec!["sort".to_owned(), crate_dir_str],
                     },
                     FormatterCommand {
-                        command: "taplo".to_owned(),
-                        args: vec!["fmt".to_owned(), manifest_path],
+                        command: "pnpm".to_owned(),
+                        args: vec!["dlx".to_owned(), "oxfmt".to_owned(), manifest_path],
                     },
                 ],
                 work_dir: String::new(),
@@ -175,9 +174,8 @@ fn get_default_formatter(config: &ResolvedCrateConfig, lang: Language) -> Option
         // `cargo sort -w` normalises all workspace Cargo.toml files so prek's
         // cargo-sort hook is a no-op; without it the hook reformats feature
         // indentation after finalize_hashes, making alef verify report stale files.
-        // `taplo fmt` then re-flows whitespace across all workspace TOML files so
-        // prek's taplo hook is similarly a no-op (best-effort: missing taplo is
-        // skipped silently via `is_tool_available`).
+        // `oxfmt` then re-flows whitespace across workspace TOML/JSON/JS/TS
+        // files consistently with the shared Kreuzberg pre-commit hook.
         Language::Ffi => Some(FormatterSpec {
             commands: vec![
                 FormatterCommand {
@@ -189,8 +187,8 @@ fn get_default_formatter(config: &ResolvedCrateConfig, lang: Language) -> Option
                     args: vec!["sort".to_owned(), "-w".to_owned()],
                 },
                 FormatterCommand {
-                    command: "taplo".to_owned(),
-                    args: vec!["fmt".to_owned()],
+                    command: "pnpm".to_owned(),
+                    args: vec!["dlx".to_owned(), "oxfmt".to_owned(), ".".to_owned()],
                 },
             ],
             work_dir: String::new(),
@@ -541,11 +539,11 @@ project_file = "{project_file}"
         let config = make_config("liter-llm");
         let spec = get_default_formatter(&config, Language::Wasm).expect("should have formatter");
         // Three commands: cargo fmt (rs files), cargo sort (Cargo.toml table order),
-        // then taplo fmt (Cargo.toml whitespace/array wrapping).
+        // then oxfmt (Cargo.toml whitespace/array wrapping).
         assert_eq!(
             spec.commands.len(),
             3,
-            "WASM must have cargo fmt + cargo sort + taplo fmt steps"
+            "WASM must have cargo fmt + cargo sort + oxfmt steps"
         );
         let fmt_cmd = &spec.commands[0];
         assert_eq!(fmt_cmd.command, "cargo");
@@ -560,12 +558,12 @@ project_file = "{project_file}"
             vec!["sort", "crates/liter-llm-wasm"],
             "cargo sort arg must be the crate directory, not the manifest path"
         );
-        let taplo_cmd = &spec.commands[2];
-        assert_eq!(taplo_cmd.command, "taplo");
+        let oxfmt_cmd = &spec.commands[2];
+        assert_eq!(oxfmt_cmd.command, "pnpm");
         assert_eq!(
-            taplo_cmd.args,
-            vec!["fmt", "crates/liter-llm-wasm/Cargo.toml"],
-            "taplo fmt must target the Cargo.toml manifest path so prek's taplo hook is a no-op"
+            oxfmt_cmd.args,
+            vec!["dlx", "oxfmt", "crates/liter-llm-wasm/Cargo.toml"],
+            "oxfmt must target the Cargo.toml manifest path"
         );
         assert!(spec.work_dir.is_empty(), "WASM formatter must run at workspace root");
     }
@@ -604,11 +602,11 @@ wasm = "crates/ts-pack-core-wasm/src/"
         let config = make_config("liter-llm");
         let spec = get_default_formatter(&config, Language::Ffi).expect("should have formatter");
         // Three commands: cargo fmt --all (rs files), cargo sort -w (Cargo.toml table
-        // order across the workspace), then taplo fmt (Cargo.toml whitespace).
+        // order across the workspace), then oxfmt (workspace TOML/JSON/JS/TS whitespace).
         assert_eq!(
             spec.commands.len(),
             3,
-            "FFI must have cargo fmt + cargo sort + taplo fmt steps"
+            "FFI must have cargo fmt + cargo sort + oxfmt steps"
         );
         let fmt_cmd = &spec.commands[0];
         assert_eq!(fmt_cmd.command, "cargo");
@@ -620,12 +618,12 @@ wasm = "crates/ts-pack-core-wasm/src/"
             vec!["sort", "-w"],
             "cargo sort must run workspace-wide so all binding crate Cargo.toml files are normalised"
         );
-        let taplo_cmd = &spec.commands[2];
-        assert_eq!(taplo_cmd.command, "taplo");
+        let oxfmt_cmd = &spec.commands[2];
+        assert_eq!(oxfmt_cmd.command, "pnpm");
         assert_eq!(
-            taplo_cmd.args,
-            vec!["fmt"],
-            "taplo fmt (no path) walks the workspace per .taplo.toml so prek's taplo hook is a no-op"
+            oxfmt_cmd.args,
+            vec!["dlx", "oxfmt", "."],
+            "oxfmt must walk the workspace like the shared pre-commit hook"
         );
         assert!(spec.work_dir.is_empty(), "FFI formatter must run at workspace root");
     }

crates/alef-e2e/src/format.rs

@@ -21,7 +21,7 @@ use tracing::warn;
 ///   flag (it's an unstable cargo-fmt-only flag in nightly), so running cargo
 ///   fmt from the e2e crate's own directory is the portable way to format a
 ///   non-workspace-member crate. `Cargo.toml` normalisation is handled by the
-///   `normalize_rust_toml` post-pass (taplo fmt), not by cargo-sort: cargo-sort
+///   `normalize_rust_toml` post-pass (oxfmt), not by cargo-sort: cargo-sort
 ///   relocates leading top-level comments to the bottom of the file, which
 ///   pushes the alef header (and `# alef:hash:` line) past the 10-line
 ///   detection window and breaks `alef verify` silently.
@@ -46,8 +46,8 @@ fn default_formatter(lang: &str) -> Option<&'static str> {
 /// Run a best-effort TOML normalization pass on the rust e2e crate's
 /// `Cargo.toml` after the language formatter has finished.
 ///
-/// Runs `taplo fmt Cargo.toml` so that downstream `prek` setups that include
-/// a taplo hook produce no further changes after `alef e2e generate`. Without
+/// Runs `pnpm dlx oxfmt Cargo.toml` so that downstream `prek` setups that
+/// include the shared oxfmt hook produce no further changes after `alef e2e generate`. Without
 /// this pass, prek would rewrite the manifest (array wrapping, indentation)
 /// after `finalize_hashes` has captured the pre-prek content, causing
 /// `alef verify` to report the file as stale.
@@ -63,14 +63,14 @@ fn default_formatter(lang: &str) -> Option<&'static str> {
 /// header inside a `[package.metadata.alef]` section that cargo-sort
 /// preserves.
 ///
-/// Taplo is invoked via `sh -c` and is best-effort: a missing binary or
+/// oxfmt is invoked via `pnpm dlx` and is best-effort: a missing binary or
 /// non-zero exit is ignored. This is intentional — alef cannot assume a
 /// particular host toolchain, and the calling project's own CI is
-/// responsible for enforcing that taplo is present when they ship the
+/// responsible for enforcing that oxfmt is present when they ship the
 /// corresponding prek hook.
 fn normalize_rust_toml(dir: &str) {
-    let taplo_cmd = format!("(cd {dir} && taplo fmt Cargo.toml >/dev/null 2>&1) || true");
-    let _ = std::process::Command::new("sh").args(["-c", &taplo_cmd]).status();
+    let oxfmt_cmd = format!("(cd {dir} && pnpm dlx oxfmt Cargo.toml >/dev/null 2>&1) || true");
+    let _ = std::process::Command::new("sh").args(["-c", &oxfmt_cmd]).status();
 }
 
 /// Run per-language formatters for all languages that had files generated.
@@ -120,8 +120,8 @@ pub fn run_formatters(files: &[GeneratedFile], e2e_config: &E2eConfig) {
             }
         }
 
-        // Rust-only TOML normalization pass: run taplo on the e2e crate's
-        // Cargo.toml so that downstream prek hooks that include taplo produce
+        // Rust-only TOML normalization pass: run oxfmt on the e2e crate's
+        // Cargo.toml so that downstream prek hooks that include oxfmt produce
         // no further changes after generation. The user's
         // `e2e_config.format[rust]` override (if any) typically only covers
         // cargo fmt — which leaves `Cargo.toml` array wrapping at its raw
@@ -158,12 +158,12 @@ mod tests {
         // cargo-sort must NOT be in the default rust formatter: it relocates
         // the alef header comments to the bottom of the file, pushing the
         // `# alef:hash:` line past the 10-line detection window and silently
-        // breaking `alef verify`. TOML normalisation is delegated to taplo via
+        // breaking `alef verify`. TOML normalisation is delegated to oxfmt via
         // `normalize_rust_toml`.
         assert!(
             !cmd.contains("cargo sort"),
             "rust formatter must NOT run cargo sort — it scrambles the alef header \
-             location in Cargo.toml. Use taplo via normalize_rust_toml instead: {cmd}"
+             location in Cargo.toml. Use oxfmt via normalize_rust_toml instead: {cmd}"
         );
     }
 
@@ -217,7 +217,7 @@ mod tests {
     #[test]
     fn test_normalize_rust_toml_is_best_effort_on_missing_dir() {
         // Should return cleanly even though the dir does not exist; both
-        // cargo-sort and taplo invocations are wrapped in `|| true`.
+        // oxfmt invocation is wrapped in `|| true`.
         normalize_rust_toml("/nonexistent/alef-e2e-test/dir");
     }
 }