Scaffolding#

Starting an app#

scripts/new.sh <Name> <target-dir> [options]

option	default	what it sets
`--template`	`sidebar`	`minimal`, `sidebar`, or `workspace`
`--slug`	the name, lowercased	the binary, `~/.<slug>`, the `.deb`, the icon file
`--id`	`io.wess.<slug>`	the macOS bundle identifier
`--repo`	`wess/<slug>`	where releases are published and the updater looks
`--desc`	a placeholder	one line, used in six manifests
`--vendor`	`Wess Cope`	the copyright holder and package author
`--email`	`[email protected]`	the Cargo author and Debian maintainer
`--accent`	`#4C6EF5`	the placeholder icon's colour
`--atlas`	`git`	`git` for a normal app, `path` to work on Atlas alongside it

It assembles the template, templates/shared, the packaging scripts, the manifests and the workflows into one directory, rewrites every placeholder, generates an icon, and makes the first commit.

The slug is stripped to lowercase letters and digits, because anything else breaks a cargo bin name, a Debian package name, or a keychain service — better here than three minutes into a release.

The MSI UpgradeCode is generated once, at scaffold time, and must never change: it is what tells Windows that version 2 replaces version 1 rather than installing beside it.

The templates#

`minimal`#

model + store + app. One window, settings, About, self-update. No async layer at all.

Start here unless you already know you need more. Its AGENTS.md says what to add when it outgrows itself, and each of those additions is one of the other two templates.

`sidebar`#

model + store + host + app. A collapsing nav rail, routed views, an async host reached through the bridge, Load<T> in the views. The Hopper shape.

This is the one to read to understand how the pieces fit.

`workspace`#

model + store + host + app, with two state scopes: a home screen listing projects, and a workspace — sidebar plus tabbed pane — for whichever one is open. The Tables shape.

Take it when the app opens something: a database, a repository, a document. The per-project state contract is the part worth having.

Renaming an app#

packaging/app.env holds every name the app is known by. bash sources it, PowerShell parses it, and the release workflow loads it into $GITHUB_ENV — so a rename is one edit there plus:

the [[bin]] name and [package.metadata.deb] block in crates/app/Cargo.toml
the strings in crates/app/src/main.rs, update.rs, and store's Store::new
atlasbuild::stamp in crates/app/build.rs

Nothing else hardcodes a name. Anything that does is a bug — that is what app.env is for.

Developing Atlas and an app together#

scripts/new.sh Acme ~/Dev/acme --atlas path

The app's Cargo.toml then points at this checkout, so a change here is visible in the app on the next build. Switch it to the git dependency before publishing.

The three templates work the same way against crates/ and are compiled in place, which is the regression test for this library: a change to a crate here is verified by building all three templates.