Name: alef-generated-bindings
Author: xberg-io

Imported from xberg-io/xberg (.ai-rulez/skills/alef-generated-bindings/SKILL.md). Install upstream with npx skills add xberg-io/xberg --skill alef-generated-bindings. Copyright stays with the author.

Alef-Generated Bindings

Files under packages/*/ and in the binding crates are generated by Alef — do not hand-edit.

Workflow

Check alef.toml before touching anything in packages/*/ or a binding crate
Modify the Rust source or alef.toml itself
task alef:generate → alef all --clean. This formats via poly as part of the run; there is no task alef:format
task alef:verify → alef verify --exit-code
task e2e:generate then task e2e:test (or task e2e:all) to verify behaviour
Commit Rust source + alef.toml + regenerated output atomically

The alef:* namespace is exactly: generate, verify, build, sync, docs, verify:readme-paths, verify:ffi-formats. Formatting is poly fmt / poly lint.

Freshness check

task alef:verify. A hand-rolled git diff over packages/ is under-scoped — generated output also lands in crates/xberg-py/, crates/xberg-php/, crates/xberg-jni/, crates/xberg-node/, crates/xberg-wasm/, crates/xberg-ffi/, packages/dart/rust/, packages/swift/rust/, and e2e/.

Alef tracks both sides under .alef/: sources_hash.cache (input hashes over the parsed Rust sources) and .alef/hashes/xberg.<lang>.output_hashes (per-file output content hashes). Neither makes a generated file safe to hand-fix — a regen restores it. Fix alef.toml or the Rust source, then regenerate and re-verify.

Key `alef.toml` sections

[workspace], [workspace.sync] (version-sync extra_paths), [workspace.docs], [workspace.poly], [workspace.generate]
[[crates]] — the Rust source crate parsed for type/function extraction, plus [[crates.source_crates]]
[crates.<lang>] — one table per binding: python, node, ruby, php, elixir, wasm, ffi, go, java, dart, kotlin_android, jni, swift, csharp, zig (each carrying exclude_functions, target_dep_overrides, stubs, …)
[crates.e2e] — e2e generation (output = "e2e", [crates.e2e.call.overrides.<lang>])
[crates.readme] — README generation (template_dir = "templates/readme", [crates.readme.languages.<lang>])
[crates.exclude], [crates.output], [crates.custom_modules], [crates.publish]

There are no [crate], [languages.*], [e2e] or [readme] top-level tables, and alef.toml declares no rename mappings — the generated Go trait type is DocumentExtractor, unchanged.

Canonical e2e tasks: task e2e:generate, e2e:build, e2e:test, e2e:all, plus e2e:verify, e2e:lint, e2e:quick, e2e:lang. Do not add legacy aliases.

Core-side edits that break a regen

New extractor struct — needs #[cfg_attr(alef, alef(skip))] on the struct declaration, not the impl block. Without it the regen aborts globally and nothing regenerates, leaving the tree silently stale. Check this first when a regen dies. (36 of the 42 modules in crates/xberg/src/extractors/ carry the attribute.)
Binding-facing types must not be #[non_exhaustive] — alef generates impl From<Mirror> for xberg::TheType with a struct literal in ~10 binding crates, and #[non_exhaustive] forbids that (E0639). Derive Default for forward-compat instead. Keep #[non_exhaustive] only on types listed in [crates.exclude].
A new enum variant on a binding-facing type breaks exhaustive matches across the generated binding crates.

Trait return types crossing the generated FFI bridge

The generated XbergOcrBackendBridge in crates/xberg-ffi/src/lib.rs marshals every trait method's return value through JSON (218 serde_json::from_str::<xberg::…> call sites today) and falls back to Default::default() on an uninitialised vtable slot, a failing host callback, or a null result. Whether a variant carries a payload is irrelevant.

Adding a method to a trait with a generated bridge means its return type needs Default + Serialize + Deserialize. Unit-only enums included.

crates/xberg-ffi is built by no ci-rust.yaml leg — only publish-path jobs — so cargo check --workspace cannot fail on it. Verify with the scoped cargo check -p xberg-ffi. That check rewrites crates/xberg-ffi/include/xberg.h and packages/go/include/xberg.h to match whatever feature set you invoked it with, which is usually not the committed one. Revert that churn rather than committing it.

Which alef answered

task alef:generate shells out to the globally installed ~/.cargo/bin/alef, not a cargo run against a sibling checkout. A source fix there has zero effect until cargo install --path . --force. Generator fixes ship in order: land upstream → release alef → bump the pinned version → regen. Regenerating against a locally modified alef produces a tree the pinned version cannot reproduce.

Install alef-generated-bindings and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

{ "ocm": "1", "id": "xberg-io-xberg-alef-generated-bindings", "kind": "skill", "name": "alef-generated-bindings", "description": "Alef-managed generated bindings in packages/* and binding crates — the regeneration workflow (task alef:generate / alef:verify), the alef.toml section layout, the core-side edits that break a regen, and the FFI bridge's JSON marshalling requirement. Load before editing anything under packages/* or a binding crate, before adding a trait method or extractor, or when regenerating or verifying Alef output.", "publisher": "xberg-io", "version": "1.0.0", "capabilities": { "domains": [ "general" ], "tags": [ "skill-md", "skills-sh" ], "languages": [ "en" ] }, "quality_prior": 0.6, "examples": [ "Alef-managed generated bindings in packages/* and binding crates — the regeneration workflow (task alef:generate / alef:verify), the alef.toml section layout, the core-side edits that break a regen, and the FFI bridge's JSON marshalling requirement. Load before editing anything under packages/* or a binding crate, before adding a trait method or extractor, or when regenerating or verifying Alef output." ], "primary": false, "metadata": { "source": { "provider": "skills.sh", "repository": "https://github.com/xberg-io/xberg", "path": ".ai-rulez/skills/alef-generated-bindings/SKILL.md", "ref": "HEAD", "url": "https://github.com/xberg-io/xberg/blob/HEAD/.ai-rulez/skills/alef-generated-bindings/SKILL.md", "key": "xberg-io/xberg/.ai-rulez/skills/alef-generated-bindings/SKILL.md" } }, "instructions": "# Alef-Generated Bindings\n\nFiles under `packages/*/` and in the binding crates are generated by Alef — do not hand-edit.\n\n## Workflow\n\n1. Check `alef.toml` before touching anything in `packages/*/` or a binding crate\n2. Modify the Rust source or `alef.toml` itself\n3. `task alef:generate` → `alef all --clean`. This formats via poly as part of the run; there\n is no `task alef:format`\n4. `task alef:verify` → `alef verify --exit-code`\n5. `task e2e:generate` then `task e2e:test` (or `task e2e:all`) to verify behaviour\n6. Commit Rust source + `alef.toml` + regenerated output atomically\n\nThe `alef:", "cost": { "context_tokens": 1189 } }

alef-generated-bindings

About