homebot-dev-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# HomeBot dev workflow (moved verbatim from AGENTS.md, 2026-10-20)

## The defect this codebase actually produces

Not crashes. **Capability that exists, works, is exported, is tested — and that nothing a user can
reach ever calls.** Every bug found in one recent full-day session was this shape: a safety
whitelist whose every caller threw before reaching it, a privacy switch that rendered only after a
failed fetch, a QA stage that inspected nothing, web tools the model was never handed, a model
downloader with no delete button, and an entire coding pillar with no button in the mode bar.

Type checkers, linters and unit tests are all green for every one of these, because the code
genuinely works.

**So before you finish anything, ask: what reaches this?** Trace outward until you arrive at
something a person can click, type or say. If you cannot, you have built another one.

## Three traps that cost real hours here

- **A control added to `AdvancedSettingsTab` is invisible by default.** Settings opens in Simple.
  This shipped a live bug — Aden could not find the Claude subscription option after a refactor.
  Decide deliberately which view a new setting belongs in.
- **Bot-opened PRs park every check at `action_required` and nothing tells you.** Required checks
  simply never report and it reads as slow CI. Ten runs were held in one day, five for three days:

  ```bash
  gh api "repos/kingithegreat/Sadie/actions/runs?status=action_required&per_page=30" \
    --jq '.workflow_runs[].id' |
    while read id; do gh api -X POST "repos/kingithegreat/Sadie/actions/runs/$id/approve"; done
  ```

  That loop is the workaround, not the fix. Copilot's PRs are held because it is treated as an
  outside contributor; GitHub added a repo setting to skip that approval, which only Aden can
  toggle. Until it is on, run the loop after every bot push.

- **A filter that matches nothing looks exactly like a clean pass.** Before believing any zero —
  a grep, a `:not()` list, a "no results found" — feed it something it *should* match. A recent
  button-grep returned two hits from a 710-line panel that actually offered six actions.

## CI tests the app; unit tests do not prove a reachable feature

Verified 2026-09-08: `ci.yml` has a root `build` job AND a Windows `widget` job that
typechecks the app, runs its full Jest suite, builds Electron, and tests overlays in the
real renderer. Separate jobs check lint and permissions. `widget-e2e-ci.yaml` runs the
three-OS E2E matrix; its `e2e-all` aggregate is required by main's branch protection.
Re-read that live protection before relying on it. Every required context must be present
and green. Neither unit tests nor a green PR prove that a media provider produced a real
video or that a user can reach a capability. Trace and exercise that path too.
Run the relevant local checks before publishing:

```bash
cd widget && npx tsc --noEmit && npm run lint && npx jest --config=jest.config.ts --runInBand --no-coverage
cd .. && npx jest && npm run docs:check
```

### Widget tests that do real I/O need an explicit timeout

A widget unit test that runs a **real handler against a loopback HTTP server** (e.g. the
ComfyUI server in `storyboard-frame-provider.test.ts`, which renders frames through a real
socket and reads files) can legitimately take multiple seconds. The Jest default is
**5000 ms**, which such tests brush right up against — that test measured ~4.6s locally and
flaked as a timeout under CI load, taking the whole `widget` job red on several PRs at once
(because they all ran the same suite). The fix was `jest.setTimeout(15_000)` in that file.

Rule: **any test that does real loopback HTTP generation or real subprocess/file work gets an
explicit `jest.setTimeout(...)` above the 5s default** (15s is fine), not the default. A
timeout on such a test is a CI-load symptom, not a product bug, and it will appear as a bare
"exceeded 5000 ms" with no failing assertion. Before believing a `widget` job is red for a
real reason, check whether it is one such timeout.

### `npm ci` needs both packages, then native rebuilds

`widget/src/main/tools/crm.ts` imports `../../../../src/crm/store` — a **root-package** file — and
`src/crm/store.ts:54` does `require('better-sqlite3')`, which Node resolves from the **root's**
`node_modules/`. Installing only `widget/` leaves 10 CRM and email tests failing on a module that
is present in widget's tree but not where the importer looks for it. `ci.yml:80-103` does this
in order; mirror it locally:

```bash
# from the repo root
npm ci --ignore-scripts                # root package (CRM store lives here)
cd widget && npm ci --ignore-scripts   # widget
npm rebuild better-sqlite3             # widget binding for Node ABI
cd .. && npm rebuild better-sqlite3    # root binding
```

`--ignore-scripts` skips electron-builder's `install-app-deps` (slow, builds against Electron's
ABI which Jest does not use). The explicit `npm rebuild better-sqlite3` after the install is
what produces the Node-ABI binary the CRM store actually loads. Without these four steps the
local `jest` run will report `crm-tools.test.ts` and `email-tool.test.ts` as failing on
`Cannot find module 'better-sqlite3' from '../src/crm/store.ts'` — and that is the same single
root cause for all 10 failures, not 10 separate bugs.

### Not every tool can run that

HomeBot ships Windows-only, and `ci.yml` runs the widget job on `windows-latest` because that is
the only platform the suite passes on. 43 test files write fixtures to `os.tmpdir()` while the
main-process file tools refuse any path outside `os.homedir()` — the same directory on Windows,
`/tmp` versus home on Linux. Measured on Linux 2026-08-24, same tree, only `TMPDIR` differing:
**79 failures across 4 suites without it, 5 in 1 suite with it.** Those last 5 are all
`sd-cpp-setup.test.ts`, which refuses on non-Windows by design (`sd-cpp-setup.ts:177`) — on Linux
that is the clean result, not a regression.

| Tool | Runs on | Can run the widget suite |
|---|---|---|
| Cline, Claude Code (local) | Aden's Windows box | Yes — no excuse for an unverified claim |
| Copilot coding agent | Linux Actions runner | Yes with `TMPDIR="$HOME/homebot-test-tmp"` — expect 5 failures in `sd-cpp-setup.test.ts`, nothing else |
| Claude Code on the web | Linux container | Same as Copilot; often no `node_modules` at all |

`.github/workflows/copilot-setup-steps.yml` installs both packages and exports `TMPDIR` for the
Copilot agent. Set it on the command line regardless — a silent fallback to `/tmp` is
indistinguishable from 92 real bugs.

**So pick work that matches where you run.** Linux-bound agents are better spent on the root
package, pure modules in `src/`, docs, CI and n8n workflows than on `widget/` UI they cannot
exercise. And if you could not run the suite, write "unit tests not run in this environment"
rather than implying green. An honest unverified is useful; a false green costs a reviewer more
than the change was worth.

## Standing rules from the Contract worth repeating

From kingithegreat/Sadie, MIT.

More from kingithegreat/Sadie