Agent-first toolchain: CLI, guest SDK and a home template

[Mathieu2301]

Three packages that let a coding agent build, check and publish a home component without being a Miakapp developer.

@miakapp/cli

Builds, checks, publishes and rolls back. Git stays the user's — the tool never commits, never bundles and never invents a control-plane endpoint.

• Closed RFC 0004 §13.2 client: capability, delivery, finalization, activation, plus the two reconciliation reads a lost response needs.
• Publisher-side pre-check of the RFC 0002 §7.2 artifact rules, so module syntax, a dynamic import, a source map or an oversized program fails before an upload capability is spent.
• One stable exit code and one stable failure kind per outcome, plus --json, so an agent decides without parsing prose. Exit 7 is unknown_outcome: the effect may already have committed, so the next step is a read, never a blind retry.
• The Home Key is read from MIAKAPP_HOME_KEY only, never from an argument. A test asserts it appears on neither stdout nor stderr.

--expected-generation is required rather than discovered, because RFC 0004 §13.2 publishes no read for the current component pointer. Asking for the number beat inventing a route.

@miakapp/component

The guest half of the ABI 1 bridge. Shapes mirror component-runtime/src/runtime-broker.ts rather than a reading of RFC 0002 — the broker is the authority, and a disagreement is a bug in this package.

• Coalesced render loop spaced to the thirty-per-second ABI rate, so a burst cannot terminate the instance.
• Typed builders for the twelve semantic node types, with closed token enums and no way to emit a key or an undefined value the bridge would reject.
• Staleness exposed rather than hidden, per RFC 0002 §12.2.
• An unknown outcome stays distinct from a failure, so a component cannot retry a call the home may already have applied.
• Local refusal of the operations the broker answers by terminating: publishing or calling while staged, suspended or inactive.

templates/home

A working home: coordinator, component, project file, 8 tests. The coordinator configuration is a pure function of its options, so the authorization that matters is tested without a relay or a network.

One test exists for an otherwise silent failure: a component receives the intersection of what it requests and what the coordinator grants, so a requirement in miakapp.yaml that stateAccess does not cover is not a publication error — the path simply never arrives.

Also fixes

canonicalHttpsUrl demanded byte-for-byte URL round-tripping, and URL re-serializes a bare origin with a trailing slash. Every origin-only control plane was rejected, including https://control.example.test, which is RFC 0004 §3's own example issuer.

Verification

bun run check:packages — 31 CLI tests, 38 component tests, 8 template tests, plus the offline artifact check on a real bundle. bun test at the root: 218 passing.

🤖 Generated with Claude Code

[Mathieu2301]

Green — and the template is now actually exercised

This PR was red on templates/home/test/home.test.ts: Cannot find package 'miakapi'. Fixing it turned up three defects that all shared one cause — the template's own check existed and nothing ran it.

	Defect	Fix
1	The root sweep reached into templates/home, which the root install cannot resolve. bun test foo/ is a substring filter, not a directory scope, so test/ also selects templates/home/test/. On Bun 1.4 the test then resolved miakapi by self-reference and passed; on the 1.2.23 CI pins, it did not.	The sweep names its files as globs. CI runs check:packages, which installs the template from scratch and runs its build, tests and miakapp check.
2	check:component typechecked examples/salon.ts — which imports by package name, as a consumer does — before build had produced dist/index.d.ts. It only ever passed on a stale dist/.	Build, then typecheck, then test.
3	bunx @miakapp/cli fetched from the registry and got a 404: the package is private. And templates/home/bun.lock was lockfileVersion 2, which 1.2.23 cannot parse — CI logged Ignoring lockfile, resolved afresh and saved a new one.	Call the miakapp binary the template's own install links. Lockfile regenerated as version 1; check:template installs --frozen-lockfile.

test/check-coverage.test.ts pins all of it. It derives rather than restates: it expands the sweep globs with Bun.Glob, walks the tree for test files, manifests and lockfiles, follows the bun run / bun --filter / cd chain, and reads the workflow. So it goes red when a test file escapes every check CI runs — not when someone forgets to update a list.

Nine negative controls, each verified red then reverted: substring filters restored · a sweep directory dropped · check:packages removed from the workflow · the template dropped from check:packages · a new unlinked project with tests · a test file in a subdirectory the globs miss · a template script bunx-ing the private CLI · a lockfile format differing from the root's · an unfrozen install in a CI-run script.

Two of the six original controls passed green on the first attempt, exactly as on #179 — the discovery had missed .ts files and root-level paths. Worth repeating: a coverage test has to be broken on purpose before it is worth anything.

Verified, on Bun 1.2.23 installed separately to match the pin, from a clean tree with no dist/ and no template install: bun run check 219/219, bun run check:packages green through cli (31), component (38) and the template (8), artifact publishable, no lockfile warning. Same result in CI on eb136c8.

[Mathieu2301]

Note issue d'une répétition de la porte de sortie de l'atelier F jouée ce matin sur l'union locale de main + #10 → #14 (détail complet en commentaire de #14).

Un point concerne directement le templates/ de cette PR : templates/home/README.md prescrit, pour sortir le template du dépôt,

bun remove miakapi @miakapp/component @miakapp/cli
bun add miakapi @miakapp/component
bun add -d @miakapp/cli

Vérifié sur le registre :

• @miakapp/component → 404, et private: true
• @miakapp/cli → 404, et private: true
• miakapi → 3.0.31, c'est-à-dire la V3

Les deux 404 sont bruyants, donc inoffensifs. Le troisième ne l'est pas : bun add miakapi réussit et installe la V3 alors que le SDK V4 d'ici est 4.0.0-alpha.0, non publié. Quelqu'un qui suit ce README obtient un template silencieusement câblé sur la génération précédente.

Je ne touche à rien : la correction dépend de la décision de publication (quels noms, quel tag, quand), et elle n'est pas de mon ressort. Mais tant que les paquets ne sont pas publiés, cette section du README promet un chemin qui n'existe pas.