c97029f654
Some checks failed
dev release / build (push) Failing after 1m47s
Registers 'init' as a cli_command in api-schema.toml and adds its lines to README.md's CLI reference, keeping xtask check-docs clean. Also adds a note to hooks_shell.rs's module header explaining why the compositor case earns a consent-gated config edit that the shell-hook module deliberately avoids, so the two don't read as contradicting each other.
615 lines
13 KiB
TOML
615 lines
13 KiB
TOML
# 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"
|
|
|
|
[[entry]]
|
|
name = "init"
|
|
kind = "cli_command"
|
|
since = "0.8"
|