v0.21.0 — Stage 2 (startapp --field, permission defaults, docs discoverability)

Stage 2 of the FTUX redesign. Four PRs bundle into one release: rustio startapp --field, structural permission defaults, a startapp pluralization + spatial-orientation fix, and rustio docs becoming a useful command.

No API breaks. Existing 0.20.x projects update by bumping rustio-admin = "0.20.0" to "0.21.0" in their Cargo.toml. Schema unchanged.

What ships

rustio startapp <name> --field <name>:<type> (PR 2.1)

Closed 8-token vocabulary — str / text / int / bigint / bool / timestamp / json / fk:<Model>. Generates a real model file with the declared fields, a matching CREATE TABLE migration, and a ModelAdmin impl whose list_display / search_fields defaults are derived from the declaration. Interactive prompt loop at TTY when no flags are passed. The "paste these lines into src/main.rs" handshake from prior releases is preserved — startapp deliberately does not edit your main.rs.

timestamp produces TIMESTAMPTZ NOT NULL (no implicit DEFAULT NOW()). json produces JSONB NOT NULL (no implicit DEFAULT '{}'). Either default would imply created_at / settings semantics that don't fit every use.

Structural permission defaults (PR 2.2)

Three groups seeded on fresh databases:

Group	Permission scope	Audience
administrator	Full system access	Owner, operator
editor	add / change / view on content models. No delete. No user / group / permission management.	Content team
viewer	view only	Auditors, read-only stakeholders

rustio user create --role accepts two new values: editor and viewer (both map to Role::User internally; authority comes from group membership). Group names lock to --role values via a CI-enforced lockstep test. The seed is guarded — projects with user-defined groups pick up zero changes on upgrade.

New doctrine doc: docs/design/DESIGN_PERMISSIONS.md.

Startapp pluralization + spatial orientation

The naive +s pluralizer that produced classs / categorys / buss was replaced with proper English rules (classes / categories / buses). Applied to both the migration filename and the admin URL.

Three new insertion markers in the scaffolded main.rs:

// rustio: modules
// rustio: imports
// rustio: models

rustio startapp output redesigned to orient the developer spatially against the markers:

MODEL CREATED  Task  (2 fields)
  ✓ src/task.rs
  ✓ migrations/0001_create_tasks.sql

3 edits in src/main.rs
  under  // rustio: modules  add  mod task;
  under  // rustio: imports   add  use task::Task;
  under  // rustio: models    add  .model::<Task>()

  $ rustio migrate apply
  $ cargo run
  admin  http://127.0.0.1:8000/admin/tasks

Operational values (paths, commands, URLs) styled via console::style — paths cyan, commands green, URL cyan-underlined, markers dim. NO_COLOR / non-TTY environments strip ANSI cleanly. Missing-marker warning fires when any of the three is absent (older projects).

rustio docs becomes useful (PR 2.4)

Probes /admin/health with a 500ms timeout. The printed output reflects whether the local docs are actually reachable right now:

RustIO docs are running on this project.

  local   http://127.0.0.1:8000/admin/docs
  online  https://docs.rs/rustio-admin

(pass --open to open the local docs in your browser)

New --open flag launches the local docs in your default browser (open / xdg-open / cmd /c start). Exits 1 if the server is unreachable. Health probe uses raw TcpStream (no HTTP-client dep) and requires the framework's x-correlation-id response header so a foreign HTTP service bound to port 8000 doesn't fool it.

Homepage gains one muted line — sign in required — under the three nav pills to explain why clicking them redirects to login when not signed in.

What was deliberately cut

PR 2.3 (doctor onboarding mode + .rustio/onboarding.json state machine) was cut per the Stage 1 Reality Audit. The audit found that rustio doctor already reads clean, and a state file would introduce hidden framework state to solve a problem nobody has.

Upgrade

# Cargo.toml
[dependencies]
rustio-admin = "0.21.0"

cargo update -p rustio-admin

Optional but recommended: the three new insertion markers (// rustio: modules / imports / models) make rustio startapp output much more useful. Add them to your existing main.rs once and the spatial-orientation output gates against them automatically.

---

Full per-PR detail in CHANGELOG.md.