All 22 apps

CandyStarter

Starter skeleton for SugarCraft apps

inspired by charmbracelet/bubbletea-app-template starter skeleton create-project

CandyStarter code coverage

composer create-project sugarcraft/candy-starter my-app --stability=dev — start from the template and you've got a working app. Demo Counter Model, PHPUnit wired up, bin/start entry point.

Install

composer create-project sugarcraft/candy-starter my-app --stability=dev

Packagist carries dev-master (plus read-only dev-legacy/* branches frozen at the pre-rename candy-mold era) today, so the quickstart passes --stability=dev — create-project refuses a dev-only package unless told to accept it. The equivalent command shape is composer create-project sugarcraft/candy-starter:dev-master my-app. Until the first release tag is cut and synced, dev-master plus the committed composer.lock are the only reproducibility lever.

This package is type: project — composer create-project is the only install verb that works the way you mean it to. Composer does not refuse a composer require of a project-type package — it is simply the wrong tool: the skeleton would land in vendor/ and merge its App\ autoload map into your host app.

Quickstart

composer create-project sugarcraft/candy-starter my-app --stability=dev
cd my-app
./bin/start

# Replace src/Counter.php with your own Model — and its matrix in tests/CounterTest.php too.
my-app/
├── composer.json         # type: project — requires sugar-core + sugar-style
├── phpunit.xml           # failOnWarning gate
├── LICENSE               # MIT
├── README.md             # the walkthrough this page mirrors
├── CALIBER_LEARNINGS.md  # template gotchas for AI-agent config sync
├── .gitignore            # vendor/, composer.lock, phpunit caches, *.gif except !.vhs/start.gif
├── .assets/icon.png      # icon for the docs site
├── bin/start             # entry point — constructs Program with the Counter model, stopSignal() exit tail (128+N)
├── src/
│   └── Counter.php       # demo Model: up/down/quit, styled border
├── tests/
│   ├── BinStartExitTailTest.php           # pins the bin's stopSignal() exit tail (128+N)
│   ├── CounterTest.php                    # pinned behaviour matrix — the test-shape reference
│   ├── ModelContractDocumentationTest.php # README fence vs interface drift guard
│   ├── ReadmeSnippetsTest.php             # lint+execute every README php fence
│   └── SiteBodyTruthTest.php              # docs site body matches the README's claims
└── .vhs/
    ├── start.tape        # CI gif recording of the running app
    └── start.gif         # the rendered demo (un-ignored by !.vhs/start.gif; CI regenerates)

What's in the box

composer create-projectThree commands and you're running. composer create-project sugarcraft/candy-starter my-app --stability=dev && cd my-app && ./bin/start.
Demo Countersrc/Counter.php — a minimal Model with up/down/quit and a styled border.
Tests in placePHPUnit 10 wired to tests/. Replace, don't reconfigure.
Entry point + exit tailbin/start is autoload + new Program(new Counter()) + run() + the stopSignal() tail that exits 128+N on signals.
Pure-Model anatomyDemonstrates all four required Model methods — init / update / view / subscriptions — plus readonly props.
Common-next-steps tableREADME points at sugarcraft/sugar-core (its Lang::t()), sugar-forms, sugar-markdown, sugar-charts, sugar-style and sugar-ssh-server — six packages you're likely to reach for next — and flags which of them are not plain renderers.

Source & demos

Try the quickstart

API

ClassMethodDescription
Counter__construct(n = 0)Creates the demo Model — its single state is the readonly count $n
Counterinit()Optional startup Cmd (null = none) — required method
Counterupdate(msg)Handle input message — returns [next Model, optional Cmd]
Counterview()Render the current frame
Countersubscriptions()Live Msg sources (null = none) — required method
Program (sugar-core)run()Start the app — provided by the sugar-core dependency, not shipped by the starter
Program (sugar-core)send(msg)Inject a Msg into a running loop — out-of-band ingress, besides the Cmd::promise() resolution and subscriptions() paths that reach update() (see the README's "Getting Msgs in")

Demos.

A VHS-recorded GIF of the demo app as it runs from the skeleton. Regenerated automatically on every push that touches the source.

Terminal recording: the counter app runs from the skeleton — Up/Down change the count, q/Esc/Ctrl+C quits

Counter from scratch

Live drive of the demo Model that ships in the skeleton — watch the framed count tick up and down before the app quits.