Getting started with SugarCraft

Three ways to get something on your screen in about five minutes — run a finished binary, scaffold an app, or taste one library. Then a router table for "I want to X, which package is that?", and the install-path truth stated once. New to the vocabulary? docs/GLOSSARY.md defines every term below.

Before you install — sugarcraft/* packages publish from dev-master until their first tags are cut, so a Composer project left on the default stable minimum-stability cannot resolve them. Add "minimum-stability": "dev", "prefer-stable": true to your root composer.json (or suffix your require with @dev).

Route A — run a finished app (no Composer needed)

Signed single-file phars ship on the releases page. Every release carries a SHA-256 sidecar; candy-code/candy-top builds from v0.1.1/v0.1.0 onward also carry an Ed25519 minisig verified against the pinned key (SECURITY.md). Requirements: PHP 8.3+.

curl -LO https://github.com/detain/sugarcraft/releases/download/candy-code/v0.1.1/candy-code.phar
curl -LO https://github.com/detain/sugarcraft/releases/download/candy-code/v0.1.1/candy-code.phar.sha256
sha256sum -c candy-code.phar.sha256
php candy-code.phar doctor        # checks your PHP extensions, then:
php candy-code.phar               # the AI coding-agent TUI
curl -LO https://github.com/detain/sugarcraft/releases/download/candy-top/v0.1.0/candy-top.phar
curl -LO https://github.com/detain/sugarcraft/releases/download/candy-top/v0.1.0/candy-top.phar.sha256
sha256sum -c candy-top.phar.sha256
php candy-top.phar                # the btop-style system monitor

A tagged phar updates itself: php candy-top.phar self-update --check, then self-update (and --rollback once if you ever want the previous file back). candy-code/v0.1.0 predates the signing key — install v0.1.1 instead; see candy-code/README.md for the full story.

Route B — build your first TUI

The starter is the shortest path to a running program: bin/start hands a Model to sugar-core's Program, which owns the event loop, raw mode, and the alt-screen. You only write the Model.

composer create-project sugarcraft/candy-starter my-app --stability=dev
cd my-app
./bin/start                       # a counter demo; q / Esc / Ctrl+C quits

A Model is the four-method contract — this compiles as-is:

<?php
declare(strict_types=1);

namespace App;

use SugarCraft\Core\{Model, Msg, Subscriptions};

final class Greeter implements Model
{
    public function init(): ?\Closure { return null; }

    /** @return array{0: Model, 1: ?\Closure} */
    public function update(Msg $msg): array { return [$this, null]; }

    public function view(): string { return 'hello'; }

    public function subscriptions(): ?Subscriptions { return null; }
}

Keys arrive as Msgs, timers and streams ride subscriptions(), and every effect is a Cmd closure — GLOSSARY.md and the sugar-core README walk each one.

Route C — taste one library

Charts are the smallest full dependency: add sugar-charts to any project and one class gives you a block-element sparkline on stdout.

composer require sugarcraft/sugar-charts
<?php
require __DIR__ . '/vendor/autoload.php';

use SugarCraft\Charts\Sparkline\Sparkline;

echo Sparkline::new([1, 3, 2, 8, 5, 4, 7, 6], 8)->view();
//  ▂▁█▅▃▇▆

I want to … → which package?

Goal Reach for
Run an AI coding agent in the terminal candy-code
Monitor CPU/memory/disks/network like btop candy-top
View an image in the terminal candy-image (CLI) / sugar-image (library)
Play a GIF or .ansi art file candy-gifview
Browse/edit files candy-files
Query databases candy-sql
Drive git with keys candy-git
Read markdown in the terminal candy-mdview
Start your own app candy-starter + sugar-core
Sparklines, bars, line charts sugar-charts
Forms and fields sugar-forms
Sortable/filterable tables sugar-table
Parse raw terminal byte-streams sugar-ansi-parser / sugar-input
Sprites, physics, animation sugar-spring, sugar-animation
Record/replay a TUI session in tests candy-vcr, sugar-testing

The full matrix with upstream comparisons is docs/MATCHUPS.md; the site mirror is sugarcraft.github.io.

Why PHP?

Because one language can cover the whole stack: the same final class that computes your business logic also returns the exact SGR bytes that paint it, with no daemon, FFI boundary, or second runtime between the two. Packages stay composer-installable like any other PHP library, and finished apps still ship to people who never touch Composer — as one signed, self-updating .phar file (Route A). PHP 8.3's strict types plus ReactPHP cover the async event loop the interactive stack runs on.

The binary-path truth (once, for everything below)

Depending on how you got a package, its launcher lives in one of four places — READMEs use vendor/bin/… and ./bin/… for different ones:

Accessibility & reduced motion

Where to read more