Skip to content

feat(examples): add hello-world reference app#16

Merged
TeoSlayer merged 1 commit into
mainfrom
feat/hello-world-example
Jun 9, 2026
Merged

feat(examples): add hello-world reference app#16
TeoSlayer merged 1 commit into
mainfrom
feat/hello-world-example

Conversation

@TeoSlayer

Copy link
Copy Markdown
Contributor

Summary

The smallest end-to-end Pilot app — single IPC method (hello.echo),
sideload-safe manifest, three-command build → install → call.
Companion to #15
and TeoSlayer/pilotprotocol#240.

Why this matters: until today the wallet was the only manifest.json in
the entire ecosystem. Anyone trying to build their first Pilot app had to
reverse-engineer the supervisor contract from a production payments app.
This is the reference for what a minimal app looks like, intentionally
sideload-safe so a developer can run make install-local without going
anywhere near the catalogue / publisher-signing flow.

Layout

examples/hello-world/
  cmd/hello/main.go       single binary, one IPC method (hello.echo)
  manifest.json           sideload-safe grants (audit.log + fs $APP/)
  Makefile                bundle / install-local / uninstall targets
  README.md               build steps, supervisor lifecycle contract, trust regimes

The committed manifest.json carries binary.sha256: "REPLACE_WITH_BUILD_OUTPUT".
make bundle copies it into bundle/ and pins the real sha there, so re-builds
never rewrite the committed file. bundle/ and bin/ are gitignored.

Test plan

  • make bundle && make install-local on the local daemon — installs cleanly,
    appstore list shows it with [sideloaded] badge
  • pilotctl appstore call io.example.hello hello.echo '{"message":"hi"}'
    returns {"echo":"hi","sideloaded":true}
  • make uninstall removes cleanly
  • Reviewer: skim the README — particularly the supervisor lifecycle
    contract table and the catalogue-vs-sideload comparison. If those read
    wrong to a new developer, the rest of the example fails too.

Dependency note

make install-local uses the --local flag from web4 PR #240 + the
sideload policy from #15. Without that pair this example would have to
be publisher-signed just to install, defeating the "smallest possible
app" premise. Land those two first; this PR can wait at the back of the
chain or merge alongside.

@codecov

codecov Bot commented Jun 9, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 0% with 57 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
examples/hello-world/cmd/hello/main.go 0.00% 57 Missing ⚠️

📢 Thoughts on this report? Let us know!

The smallest end-to-end Pilot app, sideload-safe by design. Single IPC
method, ~150 lines of Go, three-command build → install → call. Read
alongside the per-file comments — they're written as the reference for
the supervisor lifecycle contract (the six standard --flags), the
trust-regime split (catalogue vs sideload), and the manifest schema.

Layout:

  examples/hello-world/
    cmd/hello/main.go       single binary, one IPC method (hello.echo)
    manifest.json           sideload-safe grants (audit.log + fs $APP/)
    Makefile                bundle / install-local / uninstall targets
    README.md               build steps, supervisor contract, trust regimes

The committed manifest.json has sha256: "REPLACE_WITH_BUILD_OUTPUT" as
a deliberate placeholder. `make bundle` copies the manifest into
bundle/ and pins the binary's real sha256 there, so re-builds never
rewrite the committed file. bundle/ and bin/ are gitignored.

`make install-local` uses the sideload path from
#15 (the --local flag landed in web4/pilotctl
PR #240). Without that pair this example would have to be a
publisher-signed catalogue entry just to be installable, which is the
opposite of "smallest possible app."

Companion to the README that walks new developers from this app
through how an app gets supervised, what an IPC dispatcher looks like,
and where the wallet sits on the same scaffolding.
@TeoSlayer TeoSlayer force-pushed the feat/hello-world-example branch from eee302e to 32ab230 Compare June 9, 2026 06:20
@TeoSlayer TeoSlayer merged commit e32b6ec into main Jun 9, 2026
5 of 6 checks passed
@TeoSlayer TeoSlayer deleted the feat/hello-world-example branch June 9, 2026 06:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants