Hacking on homebot

Hacking on homebot

Bun + TypeScript, no runtime dependencies beyond age, git and gitleaks.
Lives in its own repo, separate from any home repo.

cd homebot
bun test               # every test runs in a temp sandbox; never touches $HOME
bun run typecheck
bun run build          # dist/homebot: one self-contained binary

~/.local/bin/homebot links to dist/homebot, so rebuild after changes. The
commit guard runs from source (bun src/cli.ts hook pre-commit) so it’s
always current.

Map

File What
src/cli.ts argument parsing, output
src/linker.ts name rules, merge, fold, conflicts, layout errors, prune
src/pack.ts repoPathFor: where a $HOME path goes in the repo
src/secrets.ts age seal/unlock, per-machine hashes
src/hook.ts pre-commit guard
src/inbox.ts items, nudge cache, notifications
src/tidy.ts the hourly chores
src/agent.ts systemd timer / launchd agent
src/unpack.ts, src/actions.ts, src/manifest/ profiles and actions
src/exports.ts package snapshots
src/triage.ts new-file questions, decisions.yml
src/save.ts, src/git.ts commit, pull, push
actions/*.sh built-in brew, apt-repos, apt, flatpak, fonts
hooks/pre-commit the guard’s entry point
shell/homebot.zsh nudge line, HOMEBOT_COUNT, Spaceship section

Conventions

  • Errors the user can fix are UserErrors and say what to run.
  • Every chore in tidy must be unable to lose data. Anything else becomes an inbox item.
  • Tests use test/fixtures.ts to build a sandbox repo + $HOME; never the real ones.
  • Config files are .yml. Old .yaml names get a rename hint, not silent support.
Previous homebot.yml