Breadway/bread
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
bread/api-schema.toml
Breadway a6973360bd
All checks were successful
dev release / build (push) Successful in 1m6s
Details
Complete Workstream F: extend check-docs to cover CLI commands, wire into CI 
Two remaining pieces from the original report, both explicitly signed
off on:

1. Wire cargo run -p xtask -- check-docs into dev-release.yml as a
   fail-fast step ahead of the release build/test, so drift between
   api-schema.toml and the real API surface now fails CI instead of
   relying on local discipline.

2. Extend api-schema.toml and check-docs to cover the bread CLI's
   command surface (bread-cli/src/main.rs's Commands/ModulesCommand/
   HooksCommand enums) against README.md's "CLI reference" section,
   not just Lua bindings/IPC methods against Documentation.md. This
   was the specific blind spot that let modules audit, hooks
   install-shell/install-git, and events --tree drift out of README
   in the first place -- check-docs would not have caught that fix
   without this extension, since its prior scope never touched the
   CLI-vs-README relationship at all.

Extraction reuses the same deliberate-textual-scanning approach as
the existing Lua/IPC extractors: depth-tracked enum variant scanning,
clap's PascalCase->kebab-case rename convention, and a hardcoded
(TABLE_VARS-style) map of which top-level Commands variants delegate
to a nested subcommand enum (Modules->ModulesCommand,
Hooks->HooksCommand), producing dotted names like modules.audit.
CLI commands are versioned against the package version (Cargo.toml),
not API_VERSION, since the CLI was never part of that versioned
contract -- documented in api-schema.toml's header.

Verified check-docs actually catches CLI/README drift, not just
passes: temporarily deleted the "bread modules audit" line from
README.md, confirmed check-docs failed with the exact right message,
restored it. 4 new unit tests cover the extraction and cross-check
logic (11 total in xtask, up from 7).
2026-08-05 13:49:57 +08:00

610 lines
12 KiB
TOML
Raw Blame History

# Bread Automation API schema — checked-in source-of-truth registry.
#
# This is Workstream F from the governance-hardening report: a *drift
# detector*, not a doc generator. `Documentation.md`'s "Dictionary: Lua API"
# section is hand-written prose (one `#### bread.<name>(...)` heading per
# binding, with worked examples and edge-case notes) — nothing here
# regenerates or reformats that prose. Instead, this file is the checked-in
# list of every `bread.*` Lua binding, IPC method, and `bread` CLI command
# that is supposed to exist right now, and `cargo run -p xtask -- check-docs`
# (wired into CI via .forgejo/workflows/dev-release.yml — fails the build on
# any drift) cross-checks it against:
#
# 1. The actual bindings registered in breadd/src/lua/mod.rs
# (`bread.set("name", ...)` calls, the nested `<x>_tbl.set(...)` calls
# for state/profile/hyprland/widget/machine/fs/json/bluetooth, and the
# handful of bindings defined via plain embedded Lua source rather than
# `bread.set` — log/warn/error/debounce/spawn/wait/wait_any/wait_all/
# workflow.*).
# 2. The actual IPC methods dispatched in breadd/src/ipc/mod.rs's
# `match req.method.as_str() { ... }` block, plus the specially-cased
# `events.subscribe` streaming upgrade.
# 3. The actual `bread` CLI commands declared in bread-cli/src/main.rs's
# `Commands`/`ModulesCommand`/`HooksCommand` enums.
# 4. Documentation.md, to make sure each lua_function/lua_table/ipc_method
# entry here still has a `#### bread.<name>` heading (Lua) or a row in
# the IPC Methods table (IPC methods).
# 5. README.md's "CLI reference" section, to make sure each cli_command
# entry here still has a `bread <name>` line there. This check exists
# because that section drifted from Documentation.md/the real CLI
# surface before check-docs covered it at all (missing `modules audit`,
# `hooks install-shell`/`install-git`, `events --tree`) — found and
# fixed by hand, then closed here so it can't recur silently.
#
# Whenever you add, rename, or remove a `bread.*` binding, an IPC method, or
# a `bread` CLI command:
# 1. Update this file to match.
# 2. Update/add the corresponding section in Documentation.md (Lua/IPC)
# or README.md's CLI reference (CLI commands).
# 3. Run `cargo run -p xtask -- check-docs` before committing — it fails
# loudly (non-zero exit) if the schema, the code, and the docs are out
# of sync. CI runs this too (dev-release.yml), so drift that slips past
# a local run still fails the build.
#
# `kind` is one of: "lua_function", "lua_table", "ipc_method", "cli_command".
#
# `since` means two different things depending on `kind`, because CLI
# commands were never part of the Bread Automation API's own versioned
# contract (see Documentation.md's "API Stability & Versioning" section —
# it's explicitly scoped to "Lua API surface + IPC methods + event
# vocabulary + runtime-state schema", not the CLI):
# - lua_function / lua_table / ipc_method: the Bread Automation API
# version (breadd/src/ipc/mod.rs's `API_VERSION`) the binding/method was
# introduced in. Anything from the original v1.0 baseline (no
# `*(Since: vX.Y)*` marker in Documentation.md) is listed as "1.0" here.
# - cli_command: the `bread`/`breadd` package version (the workspace
# crates' `Cargo.toml` `version`, kept in lockstep — see CONTRIBUTING.md)
# the command was introduced in. Pre-existing commands as of this
# registry's creation are listed as "0.7" (the release before this one);
# no attempt was made to date them more precisely than that.
#
# Format chosen: a single checked-in TOML file (this is the "a schema file
# that's checked and diffed against the actual API surface, and CI fails the
# build if they drift" option the source report names, as opposed to Rust
# attribute macros — overkill for a ~45-entry surface with no existing
# proc-macro infrastructure in this workspace). TOML specifically because
# `toml = "0.8"` is already a dependency of breadd/bread-cli/bread-shared
# (see breadd/src/core/config.rs, bread-cli/src/modules_mgmt.rs) — no new
# format/parser needed anywhere in the ecosystem.
# ---------------------------------------------------------------------------
# Lua API — Events (breadd/src/lua/mod.rs install_api + install_wait_helper)
[[entry]]
name = "on"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "once"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "filter"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "off"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "emit"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "wait"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "spawn"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "wait_any"
kind = "lua_function"
since = "1.2"
[[entry]]
name = "wait_all"
kind = "lua_function"
since = "1.2"
# ---------------------------------------------------------------------------
# Lua API — Workflows (install_workflow_helpers) *(Since: v1.2)*
[[entry]]
name = "workflow"
kind = "lua_table"
since = "1.2"
[[entry]]
name = "workflow.define"
kind = "lua_function"
since = "1.2"
[[entry]]
name = "workflow.start"
kind = "lua_function"
since = "1.2"
[[entry]]
name = "workflow.step"
kind = "lua_function"
since = "1.2"
[[entry]]
name = "workflow.status"
kind = "lua_function"
since = "1.2"
[[entry]]
name = "workflow.list"
kind = "lua_function"
since = "1.2"
# ---------------------------------------------------------------------------
# Lua API — Widgets (widget_tbl) *(Since: v1.3)*
[[entry]]
name = "widget"
kind = "lua_table"
since = "1.3"
[[entry]]
name = "widget.register"
kind = "lua_function"
since = "1.3"
[[entry]]
name = "widget.update"
kind = "lua_function"
since = "1.3"
[[entry]]
name = "widget.remove"
kind = "lua_function"
since = "1.3"
[[entry]]
name = "widget.list"
kind = "lua_function"
since = "1.3"
# ---------------------------------------------------------------------------
# Lua API — State (state_tbl)
[[entry]]
name = "state"
kind = "lua_table"
since = "1.0"
[[entry]]
name = "state.get"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "state.monitors"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "state.active_workspace"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "state.active_window"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "state.devices"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "state.power"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "state.network"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "state.profile"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "state.watch"
kind = "lua_function"
since = "1.0"
# ---------------------------------------------------------------------------
# Lua API — Profiles (profile_tbl)
[[entry]]
name = "profile"
kind = "lua_table"
since = "1.0"
[[entry]]
name = "profile.activate"
kind = "lua_function"
since = "1.0"
# ---------------------------------------------------------------------------
# Lua API — Execution, notifications, timers
[[entry]]
name = "exec"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "exec_capture"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "notify"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "after"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "every"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "cancel"
kind = "lua_function"
since = "1.0"
# ---------------------------------------------------------------------------
# Lua API — Hyprland (hyprland_tbl)
[[entry]]
name = "hyprland"
kind = "lua_table"
since = "1.0"
[[entry]]
name = "hyprland.dispatch"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "hyprland.keyword"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "hyprland.eval"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "hyprland.active_window"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "hyprland.monitors"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "hyprland.workspaces"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "hyprland.clients"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "hyprland.on_raw"
kind = "lua_function"
since = "1.0"
# ---------------------------------------------------------------------------
# Lua API — Module declaration
[[entry]]
name = "module"
kind = "lua_function"
since = "1.0"
# ---------------------------------------------------------------------------
# Lua API — Machine and filesystem (machine_tbl / fs_tbl / json_tbl)
[[entry]]
name = "machine"
kind = "lua_table"
since = "1.0"
[[entry]]
name = "machine.name"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "machine.tags"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "machine.has_tag"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "fs"
kind = "lua_table"
since = "1.0"
[[entry]]
name = "fs.write"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "fs.read"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "fs.exists"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "fs.readlink"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "fs.expand"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "json"
kind = "lua_table"
since = "1.0"
[[entry]]
name = "json.decode"
kind = "lua_function"
since = "1.0"
# ---------------------------------------------------------------------------
# Lua API — Bluetooth (bluetooth_tbl)
[[entry]]
name = "bluetooth"
kind = "lua_table"
since = "1.0"
[[entry]]
name = "bluetooth.power"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "bluetooth.powered"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "bluetooth.connect"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "bluetooth.disconnect"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "bluetooth.scan"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "bluetooth.devices"
kind = "lua_function"
since = "1.0"
# ---------------------------------------------------------------------------
# Lua API — Utilities (install_log_helpers / install_debounce)
[[entry]]
name = "log"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "warn"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "error"
kind = "lua_function"
since = "1.0"
[[entry]]
name = "debounce"
kind = "lua_function"
since = "1.0"
# ---------------------------------------------------------------------------
# IPC methods (breadd/src/ipc/mod.rs handle_request + events.subscribe)
[[entry]]
name = "ping"
kind = "ipc_method"
since = "1.0"
[[entry]]
name = "health"
kind = "ipc_method"
since = "1.0"
[[entry]]
name = "state.get"
kind = "ipc_method"
since = "1.0"
[[entry]]
name = "state.dump"
kind = "ipc_method"
since = "1.0"
[[entry]]
name = "modules.list"
kind = "ipc_method"
since = "1.0"
[[entry]]
name = "modules.reload"
kind = "ipc_method"
since = "1.0"
[[entry]]
name = "profile.list"
kind = "ipc_method"
since = "1.0"
[[entry]]
name = "profile.activate"
kind = "ipc_method"
since = "1.0"
[[entry]]
name = "emit"
kind = "ipc_method"
since = "1.0"
[[entry]]
name = "events.subscribe"
kind = "ipc_method"
since = "1.0"
[[entry]]
name = "events.replay"
kind = "ipc_method"
since = "1.0"
[[entry]]
name = "workflows.list"
kind = "ipc_method"
since = "1.2"
[[entry]]
name = "widgets.list"
kind = "ipc_method"
since = "1.3"
# ---------------------------------------------------------------------------
# CLI commands (bread-cli/src/main.rs) — checked against README.md's "CLI
# reference" section, not Documentation.md (which has no CLI section of its
# own). `since` here is the package version, not the API_VERSION — see this
# file's header.
[[entry]]
name = "reload"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "state"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "events"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "modules.list"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "modules.install"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "modules.remove"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "modules.info"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "modules.audit"
kind = "cli_command"
since = "0.8"
[[entry]]
name = "hooks.install-shell"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "hooks.install-git"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "profile-list"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "profile-activate"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "emit"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "ping"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "health"
kind = "cli_command"
since = "0.7"
[[entry]]
name = "doctor"
kind = "cli_command"
since = "0.7"
Reference in a new issue View git blame Copy permalink