fix(mvp): repair the first-run developer path

[srpatcha]

Measured against the MVP developer walk. On origin/master a new developer cannot reach a built binary, and pytest tests/unit cannot even be collected.

$ ebuild setup
[error] fatal: Remote branch main not found in upstream origin

$ pytest tests/unit
E   SyntaxError: invalid syntax
!!!! Interrupted: 1 error during collection !!!!

Six defects, each found by running the tool rather than reading it.

#	Defect
1	ebuild setup failed for everyone, on the first command. DEFAULT_CONFIG pinned branch main for both cached repos; eos and eBoot both default to master.
2	ebuild build could not run at all. dispatch.py had two consecutive else: blocks — a SyntaxError. Python does not parse a module until something imports it, so this sat on master reachable only by the command that touches it. It also made tests/unit uncollectable.
3	NinjaBackend._object_path was called twice and defined nowhere. AttributeError on every ninja build.
4	ninja was invoked as python -m ninja, so a machine with ninja properly installed still failed with No module named ninja.
5	test_ninja_backend.py asserted "-shared" was absent from a static-library file whose rule preamble always contains it. This test had never run — defect 2 made the module uncollectable.
6	The tool scaffolded a project the tool could not build. All six templates include <eos/hal.h> with no path to the repo ebuild setup had just cloned.

On defect 2

The two branches were duplicates. The RuntimeError one is kept, because tests/unit/test_dispatch.py documents the intent: an unhandled backend must fail loudly rather than silently do nothing and let the caller report a false "Build completed successfully". I initially deleted the wrong one; the existing tests caught it.

On defect 6

Templates now declare uses: [eos], resolved at build time against ~/.ebuild/repos — not written into build.yaml, because the path is a fact about one machine and build.yaml is committed.

before   6/6 stopped at "fatal error: eos/hal.h"
after    3/6 compile and reach the linker (bare-metal, linux-app, rtos-app)
         2/6 fail on template source calling APIs eos does not have
         1/6 needs arm-none-eabi, absent from this machine

Regression guard

tests/unit/test_sources_are_importable.py — every shipped .py is parsed with ast, the CLI and its lazily imported modules are imported, --help is run for each MVP command, and the cached-repo default branch is checked against the real remote with git ls-remote. A hardcoded branch name is a fact about a remote, and facts about remotes go stale.

Verification

tests/unit: 111 passed. On origin/master the same command aborts during collection. From a clean ~/.ebuild, ebuild setup and ebuild new succeed and ebuild build drives gcc.

Deliberately not fixed — each needs a decision, not a guess

• Linking: ebuild must build eos and expose its archives before any template produces a binary.
• ble-sensor and secure-boot reference APIs that do not exist (eos_ble_send, eos_ota_status_t).
• ebuild monitor, ebuild test, ebuild simulate are named in the MVP walk and do not exist as commands.
• pyproject.toml declares requires-python >=3.8 while flake8>=6.0 needs >=3.8.1, so pip install -e .[dev] cannot resolve.

[srpatcha]

Review — measured by walking the path, not reading the diff

Verified the six claimed defects against current master first. Defects 2–5 no longer reproduce — dispatch.py parses, _object_path is gone, ninja is invoked directly, and the -shared assertion was corrected by #34. Defects 1 and 6 are still live on master, and this branch is the only thing fixing them:

$ git ls-remote --heads .../eos.git main     # empty — branch does not exist
$ git clone --branch main .../eos.git
fatal: Remote branch main not found in upstream origin

So ebuild setup, step one, fails for every user on master. Confirmed.

Three failures on this branch

pytest on the branch as pushed: 256 passed, 3 failed.

1. Shared libraries regressed. test_shared_library_uses_shared_link_rule passes on master and fails here. The branch routes shared_library through the generic link rule with -shared pushed into ldflags, leaving the declared link_shared rule dead:

master   build libfoo.so: link_shared foo.o          # correct rule, but no ldflags/libs line at all
branch   build libfoo.so: link foo.o                 # ldflags = -shared ...  → rule declared and never used

Both were wrong in different ways — master silently dropped the target's ldflags and every -L/-l from uses. Fixed by keeping this branch's -L/-l wiring on the link_shared rule, and moving the platform flag into the rule preamble so darwin's -dynamiclib is decided in one place.

2. The two new test files disagree with each other. This branch adds both tests/ebuild/test_dispatch.py (expects ValueError) and tests/unit/test_dispatch.py (expects RuntimeError) for the same condition. The implementation is itself inconsistent — configure() and build() raise RuntimeError, clean() raises ValueError — so no single except guards the dispatcher. Standardised on RuntimeError, which is the type tests/unit/test_dispatch.py documents the intent for.

Step five still did not produce a binary

The PR body is accurate that 3/6 templates "reach the linker" — but reaching the linker is not the MVP. uses: [eos] resolved include dirs and returned lib_dirs=[], libraries=[]:

undefined reference to `eos_hal_init'    (and 7 more)

The cached repo is a CMake project with no install() rules, so there is nothing to point -L at until it has been built once. Added on-demand build + caching, degrading to ([], []) when cmake is absent so the developer still gets a link error naming the symbol rather than an ebuild stack trace.

Also found while there: _configure_ninja_backend did not merge _workspace_repo_paths(), so configure and build wrote different build.ninja files to the same path. Anyone running configure then ninja directly built without the EoS paths.

Two of the eight commands did not exist

ebuild test (step 6) and ebuild monitor (step 8) were not registered at all. Added both, plus configure --board (step 4). Templates now ship tests/test_main.c and a test target so step six passes on a fresh checkout.

One finding I did not fix — it belongs to eos, not here

eos_hal_linux_register() is defined in hal/src/hal_linux.c but is never called and never declared in a public header. So on a host build no backend registers, eos_hal_init() returns -1, and every subsequent HAL call silently no-ops. The scaffolded main.c ignores that return, which is why hello-eos runs and prints nothing.

hal.h documents the function as "Initialize the HAL subsystem for the current platform", so the contract and the behaviour disagree. Fixing it means either auto-registering the compiled-in default inside eos_hal_init() or exporting the register call — an eos decision, so I left the generated smoke test asserting only what is true today and said so in its comment.

Result

                         before        after
pytest                   256 / 3 fail  288 pass
golden path              3 of 8        7 of 8   (flash needs hardware)

Pushed as 13fa683. Not merging — that is your call.

[srpatcha]

Still needed after the whole backlog merges — and setup passing is an illusion

I merged every other open PR onto master in sequence (#66, #67, #68, #69, #73, #76, #63 → 247 passing) and then walked the eight-command golden path against that stack:

OK    ebuild setup
OK    ebuild new gp-app
FAIL  ebuild configure --board     no such option
FAIL  ebuild build                 fatal error: eos/hal.h: No such file or directory
FAIL  ebuild test                  no such command

So three of the eight steps still fail with the entire rest of the backlog merged. --board, test and monitor are added by this PR, and nothing else resolves the EoS headers.

ebuild setup only passed because my cache was warm

That OK is not real. ebuild/deps/__init__.py on the merged stack still reads:

"branch": "main",

and neither repo has that branch:

$ git ls-remote --heads .../eos.git main     → empty
$ git ls-remote --heads .../eBoot.git main   → empty
$ git clone --branch main .../eos.git
fatal: Remote branch main not found in upstream origin

It reported success because ~/.ebuild/repos/ was already populated from an earlier run. On a developer's first-ever ebuild setup, step one of the golden path fails. That is the defect this PR opened with, it is unfixed by everything merged since, and it is invisible to anyone whose cache is warm — which is everyone who has run the tool before.

What has changed under it

dispatch.py and ninja_backend.py here are superseded by #66, which fixes the same SyntaxError and does it first. Those hunks should be dropped in favour of #66's on rebase; what remains unique and needed is:

• ebuild/deps/__init__.py — the main → master branch fix
• templates/* — uses: [eos] plus the smoke-test template
• ebuild/cli/commands.py — _workspace_repo_paths library resolution, and the configure --board, test and monitor commands

One thing to watch on the rebase

This branch carries 1,849 CRLF lines in commands.py; the file has mixed endings, and a whole-file rewrite normalises them silently. Most of the seven conflict hunks in commands.py are that, not real disagreement. I hit the same trap on #71 — its diff read as 1,903 changed lines when the real change was 89 — and fixed it by replaying the edits onto the original bytes rather than checking out the rewritten blob.

Happy to do that rebase if you would rather I took it.

[srpatcha]

Filed #81 to track the root cause behind this, with the reproduction that was missing.

Confirming the branch default part of this PR is load-bearing, not cosmetic. The
shipped default requests a branch neither remote has:

eos    default branch: master     has 'main'? 404 Branch not found
eBoot  default branch: master     has 'main'? 404 Branch not found

$ git clone --depth 1 --branch main https://github.com/embeddedos-org/eos.git
fatal: Remote branch main not found in upstream origin
exit=128

_git_clone raises on that, cmd_setup exits 1, and steps 2-8 of the golden
path are unreachable. This is the first command a new user runs.

Worth recording why it stayed hidden: it only reproduces with no
~/.ebuild/config.yaml. Any machine that has one — mine says branch: master
— clones fine from cache and prints [ok] Setup complete. So it is invisible
to everyone who has ever had a working setup, which is everyone who would test
it. I was myself convinced this was already fixed until I ran the clone
directly.

No change requested here — master is right today and this should go in as is.

The one thing I would not want lost: the name is still a hardcoded guess in a
constant that nothing checks. Renaming either repo's default to main later
reintroduces the identical failure with the identical invisibility. #81 carries
the follow-up — drop --branch when none is configured and let the remote's
HEAD decide, which is correct by definition and survives a rename. Deliberately
kept out of this PR to avoid widening it; an explicitly configured branch would
still be honoured.

This needs a rebase before it can merge.