Lisa Blog

Lisa for developers: one SDK, one command, no private doors

· The Lisa team
developerssdkcoderflutter

This post is for the people who will build applications for Lisa. It covers what you write against, the one command that turns it into an application, and how that application reaches other people. It also says plainly which parts are still being built, because some of the most important ones are.

The rule: no private doors

Lisa’s SDK is the whole of what an application can call. It is also the whole of what Lisa’s own applications call. Mail, Surfer and the rest get no private access, and that is deliberate: if a first-party app could reach past the SDK, nothing would test the SDK, and the first outside developer would find its gaps instead of us.

The other half of the rule is about what the SDK contains. A symbol is internal until it is exported on purpose. “Public unless marked private” would let things reach you by accident, and every exported symbol is a promise we cannot take back without breaking someone. Forgetting to export something leaves it unavailable, never published by mistake. A check fails the docs build if the SDK pages and the export list disagree.

What you write against

Applications are Flutter and Dart. Lisa does not fork the engine or the framework’s foundation; it owns the widget layer, the Lisa dialect, which is where its controls, materials and window anatomy live. A stock Material button in a Lisa window is a defect.

Around the dialect sit fourteen frameworks: Core, Bus, Screen, Media, Accounts, Contacts, Calendars, Harness, Frame, Application, UI, Motion, Tray and Applet. Each one is imported as its Pack:

import 'package:lisa/core_pack.dart';
import 'package:lisa/application_pack.dart';
import 'package:lisa/frame_pack.dart';

There is no umbrella import. The import list is the dependency list, so a reviewer can read what a program stands on from the top of main.dart, and a tray-only app that never imports Frame visibly never has a window.

If you know Xcode, a Pack is what a framework’s headers are in a macOS SDK. The difference is when the code binds. Dart cannot share code between snapshots, so what you use of a framework is compiled into your bundle, and only the daemons and the engine are shared at run time, over the bus. An app never hand-writes a bus call: the clients are generated from the same contracts the daemons are.

The guides walk it the way a person learns it. Counter is one small application that touches the whole tree: bundle, manifest, window, menu, preference, undo, badge, motion and an agent tool.

One command: coder

Application tooling is verbs of one command, not a project file, an editor plug-in or a folder of helper scripts:

verb what it does
coder create a new application tree, with the surfaces you ask for: a window, a tray, an applet
coder build one snapshot per entry point, in the pinned toolchain
coder check the analyzer, the tests, the goldens, the schemas and the contract checks
coder package the .app bundle, validated, with a receipt of what is inside
coder run · coder deploy launch it here, or on another device, under the developer launch identity
coder doctor is this machine ready to build
coder publish … validate a bundle and prepare it for Harbor

Two rules hold across all of them. The bundle and the tree agree, or check refuses. And every verb is reproducible: the same tree and the same toolchain pin give the same bytes, and the receipt package writes says which bytes and which specification the app was built against.

Every verb takes --json, because the same verbs are what Lisa’s agents call. When the Harness runs one, it is jailed, guard-checked and recorded like any other agent action. There is one implementation of each check, because a second implementation of a check is a check that drifts.

Coder is the application around the command, Lisa’s equivalent of Xcode, and like Xcode you install it: turn on Developer Mode, install Coder from Harbor, and coder comes with it. The OS itself ships no developer tooling. It runs a verb for every action it offers. Its agents are the system’s Harness, wearing Coder’s window, so the coding help you get there is the same loop that serves every other surface.

Nothing is layered onto the OS

Lisa’s root is immutable: the bytes that boot are the bytes that were tested. So the developer toolchain never touches it. coder builds inside a rootless container that uses the same Fedora repositories and the same signing that build the image, so there is no second supply chain. Everything a developer adds lives under /var, and coder reset is a real recovery rather than a reinstall.

Developer Mode

Not every person is a developer. Developer Mode is a per-device setting, off by default, turned on in Settings by an administrator. It exists only on a desktop; a headless machine refuses every developer path. Behind it is the developer launch identity: an app launched from your source tree runs under an identity that says so, and the system can treat it differently from a signed bundle.

Reaching people: Harbor

Every app reaches a person’s machine through Harbor, in a signed set, the same way Lisa’s own apps do. coder publish prepares an unsigned candidate; the release authority signs. For developers outside Lisa, the door is the Developer Program, behind your Lisa ID: you enrol, prove a reverse domain you control, and get a publisher key you made on your own machine. The docs and the reference at lisaos.dev stay free and public; only publishing needs the program.

What is not built

A lot, and it is better said here than discovered:

  • No developer tool is on the image today. The installed release has Coder’s window, which is a Harness conversation, and no coder, dart or flutter. The editor, the project browser and hot reload are planned.
  • Coder still ships in the image. We seed it there for testing, and that goes in a coming release.
  • Developer Mode is not wired. No daemon holds its marker yet, so every developer path today runs under ordinary identity.
  • The verbs have never run end to end on a seated machine as one developer workflow. They have built real bundles in a build container, and we rebuild Lisa’s own apps on our test machine without rebuilding the OS.
  • The import rule is not enforced in bundles yet. No check reads an app’s imports, and three of our own apps still reach past the Packs.
  • The Developer Program is written and not built. No outside publisher exists.

Everything above is in the docs, which are the specification Lisa is built to: Developer, SDK, Coder and Harbor.

← All posts