Breadway/bos
1
0
Fork 0
Code Issues Pull requests Projects Releases 5 Packages Wiki Activity Actions

Extract bos-settings to its own repo; add breadhelp; JSON-driven Hyprland config

Browse source 
bos-settings moves to git.breadway.dev/Breadway/bos-settings (full history
preserved via git-filter-repo) so its release cadence is decoupled from
BOS's own. breadhelp takes its place as this repo's workspace member: a
GTK4 onboarding/help center replacing the old bos-welcome/bos-keybinds
bash scripts with searchable guides, an interactive keybind viewer
(sourced from the new keybinds.toml, not parsed out of hyprland.lua or
hardcoded), a troubleshooting wizard with one-click fixes, and a proper
first-run tour. bos-netcheck extracts bos-welcome's network-check half,
which still needs to run every login independent of breadhelp's own
first-run gating.

hyprland.lua's keybinds/settings/monitors/autostart are now JSON-driven
(binds.json/settings.json/monitors.json/autostart.json) with every
loader pcall-wrapped and falling back to hardcoded defaults per field on
bad or missing config, so bread* apps (bos-settings' new editors, and
breadhelp's keybind viewer) can read/write this config without ever
being able to leave the compositor unable to start.

CI's package.yml now builds breadhelp instead of bos-settings on tag
push; bos-settings needs its own equivalent workflow in its new repo
(not yet set up).
This commit is contained in:
Breadway 2026-07-05 09:16:14 +08:00
parent 434efcea22
commit 664298b6b4
105 changed files with 3280 additions and 5149 deletions
Download patch file Download diff file Expand all files Collapse all files

56
iso/airootfs/etc/skel/.config/hypr/scripts/display/monitors.lua Normal file
View file

@ -0,0 +1,56 @@
-- scripts/display/monitors.lua — loads monitors.json (an array of monitor
-- rules) and applies each via hl.monitor(). Failsafe: an empty or entirely
-- invalid monitors.json is treated the same as a missing one — falling back
-- to the single generic wildcard rule — because applying *zero* monitor
-- rules risks an unconfigured/black-screen session, unlike settings.json or
-- autostart.json where "apply nothing extra" is a legitimate user choice.
local json = dofile(os.getenv("HOME") .. "/.config/hypr/scripts/lib/json.lua")
local DEFAULT_MONITORS = {
{ output = "", mode = "preferred", position = "auto", scale = "auto" },
}
local function valid_entry(e)
return type(e) == "table" and type(e.output) == "string"
end
local function load_monitors()
local path = os.getenv("HOME") .. "/.config/hypr/monitors.json"
local parsed = json.load(path)
if type(parsed) ~= "table" or type(parsed.monitors) ~= "table" then
return DEFAULT_MONITORS
end
local valid = {}
for _, entry in ipairs(parsed.monitors) do
if valid_entry(entry) then
valid[#valid + 1] = {
output = entry.output,
mode = (type(entry.mode) == "string" and entry.mode) or "preferred",
position = (type(entry.position) == "string" and entry.position) or "auto",
scale = entry.scale ~= nil and entry.scale or "auto",
mirror = type(entry.mirror) == "string" and entry.mirror or nil,
}
end
end
if #valid == 0 then
return DEFAULT_MONITORS
end
return valid
end
local monitors = load_monitors()
local applied_any = false
for _, m in ipairs(monitors) do
if pcall(hl.monitor, m) then
applied_any = true
end
end
-- Every entry failed to apply (e.g. Hyprland rejected values that still
-- passed our type checks) — guarantee a usable session rather than leaving
-- every monitor unconfigured.
if not applied_any then
pcall(hl.monitor, DEFAULT_MONITORS[1])
end

35
iso/airootfs/etc/skel/.config/hypr/scripts/input/binds.lua Normal file
View file

@ -0,0 +1,35 @@
-- scripts/input/binds.lua — loads binds.json into { default_mods, bindings }.
-- Simpler than the multi-keyboard-layout version some personal configs use
-- (BOS ships one fixed layout, no per-layout bind switching needed): just
-- reads `default_mods` + the flat `bindings` array.
local json = dofile(os.getenv("HOME") .. "/.config/hypr/scripts/lib/json.lua")
local function normalize_mods(value, fallback)
local mods = {}
if type(value) == "table" then
for _, item in ipairs(value) do
if type(item) == "string" and item ~= "" then
mods[#mods + 1] = item
end
end
end
if #mods == 0 then
for _, mod in ipairs(fallback or {}) do
mods[#mods + 1] = mod
end
end
return mods
end
return function(configPath)
local parsed = json.load(configPath)
if type(parsed) ~= "table" then
return { default_mods = { "SUPER" }, bindings = {} }
end
return {
default_mods = normalize_mods(parsed.default_mods, { "SUPER" }),
bindings = type(parsed.bindings) == "table" and parsed.bindings or {},
}
end

124
iso/airootfs/etc/skel/.config/hypr/scripts/input/keybinds.lua Normal file
View file

@ -0,0 +1,124 @@
-- scripts/input/keybinds.lua — turns binds.json entries into real hl.bind()
-- calls. Ported from a personal modular Hyprland config using the same
-- `hl` API; action_builders covers every dispatcher shape BOS's keybinds
-- actually use (exec, window management, focus/move/resize, workspaces,
-- mouse, media keys).
return function(ctx)
local function split_mods(value)
local mods = {}
for raw_mod in tostring(value):gmatch("[^+]+") do
local mod = raw_mod:gsub("^%s+", ""):gsub("%s+$", "")
if mod ~= "" then
mods[#mods + 1] = mod
end
end
return mods
end
-- `allow_empty`: an explicit `"mods": []` in binds.json (media keys,
-- which must bind with no modifier at all) must NOT fall back to
-- default_mods — only an *omitted* `mods` field should.
local function normalize_mods(value, fallback, allow_empty)
if value == nil then
return fallback
end
if type(value) ~= "table" then
return fallback
end
if #value == 0 then
return allow_empty and {} or fallback
end
local mods = {}
for _, item in ipairs(value) do
if type(item) == "string" then
for _, mod in ipairs(split_mods(item)) do
mods[#mods + 1] = mod
end
end
end
if #mods == 0 then
return fallback
end
return mods
end
local defaultMods = normalize_mods(ctx.default_mods, { "SUPER" }, false)
local bindings = ctx.bindings or {}
local function bind_string(mods, key)
if type(key) ~= "string" or key == "" then
return nil
end
if #mods == 0 then
return key
end
return table.concat(mods, " + ") .. " + " .. key
end
local action_builders = {
exec = function(entry)
return hl.dsp.exec_cmd(entry.command)
end,
close = function()
return hl.dsp.window.close()
end,
exit = function()
return hl.dsp.exit()
end,
float = function()
return hl.dsp.window.float({ action = "toggle" })
end,
fullscreen = function()
return hl.dsp.window.fullscreen({ action = "toggle" })
end,
pseudo = function()
return hl.dsp.window.pseudo({ action = "toggle" })
end,
layout = function(entry)
return hl.dsp.layout(entry.layout)
end,
focus = function(entry)
return hl.dsp.focus({ direction = entry.direction, workspace = entry.workspace })
end,
focus_last = function()
return hl.dsp.focus({ urgent_or_last = true })
end,
move = function(entry)
return hl.dsp.window.move({ workspace = entry.workspace })
end,
move_dir = function(entry)
return hl.dsp.window.move({ direction = entry.direction })
end,
resize = function()
return hl.dsp.window.resize()
end,
resize_dir = function(entry)
return hl.dsp.window.resize({ x = entry.x or 0, y = entry.y or 0, relative = true })
end,
drag = function()
return hl.dsp.window.drag()
end,
}
-- One bad entry (unknown action, missing field a builder needs) must
-- never take down every other bind — skip it and keep going instead of
-- asserting/erroring, which would abort binds.json loading entirely.
for _, entry in ipairs(bindings) do
local builder = action_builders[entry.action]
if builder then
local ok, result = pcall(function()
local mods = normalize_mods(entry.mods, defaultMods, true)
local bind = bind_string(mods, entry.key)
local action = builder(entry)
if bind and action then
hl.bind(bind, action, entry.options)
end
end)
if not ok then
print("breadhelp/hyprland: skipping bad bind entry (" .. tostring(entry.action) .. "/" .. tostring(entry.key) .. "): " .. tostring(result))
end
else
print("breadhelp/hyprland: skipping bind entry with unknown action: " .. tostring(entry.action))
end
end
end

180
iso/airootfs/etc/skel/.config/hypr/scripts/lib/json.lua Normal file
View file

@ -0,0 +1,180 @@
-- scripts/lib/json.lua
local M = {}
function M.parse(str)
local s = str
local pos = 1
local len = #s
local function skipws()
while pos <= len and s:sub(pos,pos):match('%s') do pos = pos + 1 end
end
local function parse_string()
if s:sub(pos,pos) ~= '"' then error('expected string') end
pos = pos + 1
local out = {}
while pos <= len do
local c = s:sub(pos,pos)
if c == '"' then pos = pos + 1; return table.concat(out) end
if c == '\\' then
local n = s:sub(pos+1,pos+1)
if n == '"' then out[#out+1] = '"'; pos = pos + 2
elseif n == '\\' then out[#out+1] = '\\'; pos = pos + 2
elseif n == '/' then out[#out+1] = '/'; pos = pos + 2
elseif n == 'b' then out[#out+1] = '\b'; pos = pos + 2
elseif n == 'f' then out[#out+1] = '\f'; pos = pos + 2
elseif n == 'n' then out[#out+1] = '\n'; pos = pos + 2
elseif n == 'r' then out[#out+1] = '\r'; pos = pos + 2
elseif n == 't' then out[#out+1] = '\t'; pos = pos + 2
elseif n == 'u' then
local hex = s:sub(pos+2, pos+5)
local code = tonumber(hex, 16)
if code then out[#out+1] = utf8.char(code) end
pos = pos + 6
else
pos = pos + 2
end
else
out[#out+1] = c
pos = pos + 1
end
end
error('unclosed string')
end
local function parse_value()
skipws()
local c = s:sub(pos,pos)
if c == '"' then return parse_string()
elseif c == '{' then
return parse_object()
elseif c == '[' then
return parse_array()
elseif c:match('[%d%-]') then
local start = pos
while s:sub(pos,pos):match('[%d+%-.eE]') do pos = pos + 1 end
local num = tonumber(s:sub(start, pos-1))
return num
elseif s:sub(pos,pos+3) == 'null' then pos = pos + 4; return nil
elseif s:sub(pos,pos+3) == 'true' then pos = pos + 4; return true
elseif s:sub(pos,pos+4) == 'false' then pos = pos + 5; return false
else
error('unexpected value at ' .. pos)
end
end
function parse_array()
if s:sub(pos,pos) ~= '[' then error('expected [') end
pos = pos + 1
skipws()
local arr = {}
if s:sub(pos,pos) == ']' then pos = pos + 1; return arr end
while true do
skipws()
local val = parse_value()
table.insert(arr, val)
skipws()
local c = s:sub(pos,pos)
if c == ']' then pos = pos + 1; break
elseif c == ',' then pos = pos + 1; skipws()
else error('expected , or ]') end
end
return arr
end
function parse_object()
if s:sub(pos,pos) ~= '{' then error('expected {') end
pos = pos + 1
skipws()
local obj = {}
if s:sub(pos,pos) == '}' then pos = pos + 1; return obj end
while true do
skipws()
local key = parse_string()
skipws()
if s:sub(pos,pos) ~= ':' then error('expected :') end
pos = pos + 1
skipws()
local val = parse_value()
obj[key] = val
skipws()
local c = s:sub(pos,pos)
if c == '}' then pos = pos + 1; break
elseif c == ',' then pos = pos + 1; skipws()
else error('expected , or }') end
end
return obj
end
skipws()
return parse_value()
end
function M.load(path)
local ok, fh = pcall(io.open, path, "r")
if not ok or not fh then
return nil, "unable to open file"
end
local content = fh:read("*a")
fh:close()
local success, parsed = pcall(M.parse, content)
if not success then
return nil, parsed
end
return parsed
end
function M.encode(value, indent)
indent = indent or 0
local indent_str = string.rep(" ", indent)
local next_indent_str = string.rep(" ", indent + 1)
if value == nil then
return "null"
elseif type(value) == "boolean" then
return value and "true" or "false"
elseif type(value) == "number" then
return tostring(value)
elseif type(value) == "string" then
return '"' .. value:gsub('\\', '\\\\'):gsub('"', '\\"'):gsub('\n', '\\n'):gsub('\r', '\\r'):gsub('\t', '\\t') .. '"'
elseif type(value) == "table" then
local is_array = true
local max_idx = 0
for k in pairs(value) do
if type(k) ~= "number" then
is_array = false
break
end
max_idx = math.max(max_idx, k)
end
if is_array and max_idx == #value then
if max_idx == 0 then
return "[]"
end
local items = {}
for i = 1, max_idx do
table.insert(items, next_indent_str .. M.encode(value[i], indent + 1))
end
return "[\n" .. table.concat(items, ",\n") .. "\n" .. indent_str .. "]"
else
local items = {}
for k, v in pairs(value) do
table.insert(items, next_indent_str .. M.encode(tostring(k), 0) .. ": " .. M.encode(v, indent + 1))
end
if #items == 0 then
return "{}"
end
table.sort(items)
return "{\n" .. table.concat(items, ",\n") .. "\n" .. indent_str .. "}"
end
else
return "null"
end
end
return M

45
iso/airootfs/etc/skel/.config/hypr/scripts/system/autostart.lua Normal file
View file

@ -0,0 +1,45 @@
-- scripts/system/autostart.lua — loads the *extra* (user-toggleable)
-- autostart list from autostart.json. Returns just the enabled commands, in
-- order. The core bootstrap sequence (theme generation, dark-mode gsettings,
-- polkit agent, wallpaper daemon, breadd's Wayland-env fix, breadclipd) is
-- deliberately NOT exposed here — it's timing/order-sensitive infrastructure,
-- not something a settings UI should let a user disable, so it stays
-- hardcoded in hyprland.lua itself.
--
-- Failsafe: unlike monitors.json, an empty or all-disabled result here is a
-- legitimate user choice (they don't want breadbar/hypridle/etc), so this
-- only falls back to defaults on a missing/malformed file — never just
-- because the valid result happens to be empty.
local json = dofile(os.getenv("HOME") .. "/.config/hypr/scripts/lib/json.lua")
local DEFAULT_EXTRA = {
{ command = "breadbar", enabled = true },
{ command = "hypridle", enabled = true },
{ command = "bos-netcheck", enabled = true },
{ command = "breadhelp --autostart", enabled = true },
}
return function()
local path = os.getenv("HOME") .. "/.config/hypr/autostart.json"
local parsed = json.load(path)
local entries
if type(parsed) ~= "table" or type(parsed.extra) ~= "table" then
entries = DEFAULT_EXTRA
else
entries = parsed.extra
end
local commands = {}
for _, entry in ipairs(entries) do
if type(entry) == "table" and type(entry.command) == "string" and entry.command ~= "" then
local enabled = entry.enabled
if type(enabled) ~= "boolean" then
enabled = true
end
if enabled then
commands[#commands + 1] = entry.command
end
end
end
return commands
end

121
iso/airootfs/etc/skel/.config/hypr/scripts/ui/settings.lua Normal file
View file

@ -0,0 +1,121 @@
-- scripts/ui/settings.lua — loads settings.json over hardcoded defaults and
-- applies via hl.config(). Failsafe in two layers:
-- 1. every leaf value is type-checked against its default individually, so
-- one bad field (wrong type, typo) falls back to just that field, not
-- the whole file;
-- 2. the actual hl.config() application is pcall'd — if Hyprland itself
-- rejects a well-typed-but-semantically-bad value, we fall back to
-- re-applying pure hardcoded defaults, so the session always comes up
-- with a normal, usable layout instead of erroring out mid-config-load.
local json = dofile(os.getenv("HOME") .. "/.config/hypr/scripts/lib/json.lua")
local DEFAULTS = {
gaps_in = 5,
gaps_out = 10,
border_size = 2,
active_border = "rgba(88c0d0ff)",
inactive_border = "rgba(4c566aff)",
layout = "dwindle",
resize_on_border = true,
rounding = 8,
blur_enabled = true,
blur_size = 6,
blur_passes = 2,
shadow_enabled = true,
shadow_range = 12,
shadow_render_power = 3,
kb_layout = "us",
follow_mouse = 1,
natural_scroll = true,
}
local function num(v, fallback)
if type(v) == "number" then return v end
return fallback
end
local function bool(v, fallback)
if type(v) == "boolean" then return v end
return fallback
end
local function str(v, fallback)
if type(v) == "string" and v ~= "" then return v end
return fallback
end
local function load_overrides()
local path = os.getenv("HOME") .. "/.config/hypr/settings.json"
local parsed = json.load(path)
if type(parsed) ~= "table" then
return {}
end
return parsed
end
local o = load_overrides()
local merged = {
gaps_in = num(o.gaps_in, DEFAULTS.gaps_in),
gaps_out = num(o.gaps_out, DEFAULTS.gaps_out),
border_size = num(o.border_size, DEFAULTS.border_size),
active_border = str(o.active_border, DEFAULTS.active_border),
inactive_border = str(o.inactive_border, DEFAULTS.inactive_border),
layout = str(o.layout, DEFAULTS.layout),
resize_on_border = bool(o.resize_on_border, DEFAULTS.resize_on_border),
rounding = num(o.rounding, DEFAULTS.rounding),
blur_enabled = bool(o.blur_enabled, DEFAULTS.blur_enabled),
blur_size = num(o.blur_size, DEFAULTS.blur_size),
blur_passes = num(o.blur_passes, DEFAULTS.blur_passes),
shadow_enabled = bool(o.shadow_enabled, DEFAULTS.shadow_enabled),
shadow_range = num(o.shadow_range, DEFAULTS.shadow_range),
shadow_render_power = num(o.shadow_render_power, DEFAULTS.shadow_render_power),
kb_layout = str(o.kb_layout, DEFAULTS.kb_layout),
follow_mouse = num(o.follow_mouse, DEFAULTS.follow_mouse),
natural_scroll = bool(o.natural_scroll, DEFAULTS.natural_scroll),
}
local function build_hl_config(v)
return {
general = {
gaps_in = v.gaps_in,
gaps_out = v.gaps_out,
border_size = v.border_size,
col = {
active_border = v.active_border,
inactive_border = v.inactive_border,
},
layout = v.layout,
resize_on_border = v.resize_on_border,
},
decoration = {
rounding = v.rounding,
active_opacity = 1.0,
inactive_opacity = 1.0,
blur = {
enabled = v.blur_enabled,
size = v.blur_size,
passes = v.blur_passes,
new_optimizations = true,
},
shadow = {
enabled = v.shadow_enabled,
range = v.shadow_range,
render_power = v.shadow_render_power,
},
},
input = {
kb_layout = v.kb_layout,
follow_mouse = v.follow_mouse,
touchpad = { natural_scroll = v.natural_scroll },
},
dwindle = { preserve_split = true },
animations = { enabled = true },
misc = { disable_hyprland_logo = true, disable_splash_rendering = true },
}
end
local ok = pcall(hl.config, build_hl_config(merged))
if not ok then
pcall(hl.config, build_hl_config(DEFAULTS))
end