Skip to content
alpha 0.1.0-alpha.7 is on crates.io. Install the CLI Start here

Crates and layering

The Phase 0 workspace is in the tree. This chapter is the contract it satisfies and the map for what comes next; it is deliberately more specific than the README.

Crates

Eleven crates are materialized now; the rest arrive with the phase that needs them.

CrateKindResponsibilityStatus
aurolibraryfacade re-exporting the supported API surface; services and tray are opt-in featuresPhase 0-2, in tree
auro-clibinarynew, dev, build, bundle, generate-key, manifest, delta, notarize, bench, doctorPhase 0-2, in tree
auro-corelibraryconfig schema, state store, lifecycle events, single-instance guard and forwarding; window manager and event delivery live in the facadePhase 1, in tree (config, state, lifecycle, instance)
auro-uilibraryGPUI re-export, tokens, minimal primitives (Button with keyboard activation); no component toolkit (ADR 0009)Phase 0-2, in tree (re-exports, Button, tokens)
auro-ipclibrarytyped transport, command schemas, runtime bridgePhase 1, in tree
auro-macrosproc-macro#[command], generate_handler!Phase 0, in tree
auro-permslibrarycapability manifests and runtime enforcement (spec 0016)Phase 2, in tree
auro-pluginslibraryplugin manifest and host (in-process and out-of-process)planned, Phase 3
auro-serviceslibraryplatform services: autostart, notifications, keychain, global shortcuts, tray, deep links (specs 0017-0022)Phase 2, in tree
auro-bundlelibraryplatform packaging via tauri-bundler (spec 0010)Phase 2, in tree
auro-signlibraryEd25519 keys, signatures, SHA-256 (spec 0011)Phase 2, in tree
auro-updatelibrarysigned manifests, stage/delta/rollout runtime, platform apply and journal-driven restart/rollback (specs 0012-0014, 0025-0032)Phase 2, in tree

Dependency rules

  1. One direction. A crate may depend on the layer below it. Cycles are a design error, not a Cargo.toml problem.
  2. auro-core composes; it is not a dumping ground. Anything that only one platform or one subcommand needs belongs in that crate.
  3. auro-ui has no policy. No permission checks, no filesystem access, no config reads. A primitive that needs data takes it as an argument.
  4. auro-perms has no I/O. It answers "is this capability granted for this subject?" and returns a verdict. Enforcement points live at the call sites that perform the effect.
  5. GPUI is not re-exported wholesale. auro-ui re-exports only the GPUI surface Auro's primitives use, so upstream churn is absorbed in one place.
  6. No toolkit in the framework. gpui-component and similar crates are application dependencies, initialized through App::setup and wrapped with App::root_with (ADR 0009).

Rules for tracking GPUI upstream

  • Pin GPUI by exact version. Floating a git dependency is how the compat layer becomes a fork.
  • Vendor a patch only when the upstream bug blocks a release; keep the patch in one module with a link to the upstream issue.
  • Nothing outside auro-ui imports gpui directly. That includes examples unless they are explicitly demonstrating the escape hatch.

Naming

  • Crates: auro-* in the manifest, auro_* in code, auro as the user-facing facade.
  • Public API is added to auro::prelude only when it is stable enough to promise.
  • Internal modules may be reorganised freely before 1.0; public items may not move without a changelog entry.

Open questions

  • Whether auro is a separate facade crate or auro-core re-exported under a shorter name.
  • Whether auro-update and auro-sign are two crates or one crate with features. They are named separately in the roadmap, and their consumers are narrow (auro-cli and auro-update), so this can be settled when the updater API stabilizes.