Fimeg/souveraine
Watch
1
0
Fork
You've already forked souveraine
 0
Code Releases Activity
souveraine/docs/tasks/quickshell-surface-package.md

5.2 KiB
Raw Blame History

task_id title status priority phase created references
souveraine-surface-001 QuickShell surface package — explicit, reversible desktop adoption in_progress high delivery 2026-07-13 docs/tasks/souveraine-cicd-pipeline.md, surfaces/quickshell/deploy.sh

QuickShell Surface Package

Outcome

souveraine remains the non-visual substrate package: server binary, user unit, and no ownership of ~/.souveraine or ~/.config. The QuickShell body splits by device profile: laptop and phone share Souveraine's channel protocol, not a top bar, dock, layout, or interaction density. Installing/upgrading a package never silently replaces a person's ii shell, top bar, dock, or local QuickShell changes.

What exists now

  • The running laptop package ships only /usr/bin/souveraine, its user unit, and license files. It correctly updates with pacman, but contains no QML.
  • surfaces/quickshell/ is the canonical source for shared channel code and a currently mixed development overlay. It is not a universal surface manifest: pill/shell.qml and the compact rotating phone bar do not belong on a laptop, whose bar intentionally has more visible controls.
  • deploy.sh is the development deployment path; it manages symlinks and retains one .upstream copy for ordinary upstream files.
  • The laptop had an older AiChat.qml; its /agent and /resume commands were absent even though the server and Ai.qml were current. The live panel is now linked to the canonical file, with the prior copy backed up.

Safety contract

  1. Pacman places only package-owned assets under /usr/share/souveraine/ and an adoption tool under /usr/bin/ or /usr/libexec/.
  2. The package name and manifest are profile-specific: at minimum souveraine-surface-laptop and souveraine-surface-phone; shared QML lives in a common asset layer. A laptop installer never considers phone files, and vice versa.
  3. The adoption tool defaults to a dry run: it names every managed, new, and replacement target.
  4. A normal --apply succeeds only when targets are new or already managed by Souveraine.
  5. Replacements require --adopt; each conflicting file or symlink is copied to a timestamped *.pre-souveraine-* backup before the overlay changes it.
  6. --uninstall restores the original .upstream files where available and otherwise removes only Souveraine-managed symlinks. It never removes user data, agent memory, or unrelated ii files.
  7. Package upgrades do not run adoption automatically. They update the assets; the user reviews and applies their desktop changes explicitly.

First cut — in progress

  • Expose deploy.sh --manifest so package tooling and the developer path share a single authoritative list of managed files.
  • Add scripts/install-quickshell-surface.sh as a safe inventory tool. Its apply/adopt mode is deliberately disabled until profiles exist; it cannot make the mixed overlay look universally safe.
  • Split the current development manifest into common, laptop, and phone manifests. Classify every file by actual layout and interaction contract; do not infer a laptop layout from phone work or vice versa.
  • Re-enable safe apply/adopt only against a selected profile. Exercise its dry-run, clean apply, conflict refusal, adoption backup, and uninstall behaviour in disposable configs for both devices.
  • Add a targeted --only <target> mode within the chosen profile so a small repair such as AiChat can be adopted without touching a bar or dock.

Package design — next cut

  1. Add packaging/arch/PKGBUILD.surface-common, .surface-laptop, and .surface-phone (arch=('any')). The common package supplies the channel code; each profile supplies only its own QML/assets and adoption manifest.
  2. Make the command resolve packaged assets first, with a checked-out repo retained as an explicit developer override.
  3. Extend the CI release job to build/sign/publish the surface package once per edge release alongside both binary packages.
  4. Add a narrow integration test using a temporary $XDG_CONFIG_HOME; verify no automatic overwrite and that --adopt preserves every conflict.
  5. On phone and laptop, install the appropriate profile package with pacman, run the profile preview, then choose adoption deliberately. The phone's existing live symlink development loop remains valid until this proves itself.

Later: desktop profile

souveraine-desktop is a meta-package that depends on the substrate and surface packages. It does not adopt the surface itself; its post-install message directs the user to the preview command. This gives a future fresh machine one clear install target without sacrificing ownership of its shell.

Acceptance

  • pacman -S souveraine never changes a QuickShell file.
  • pacman -S souveraine-surface-laptop and pacman -S souveraine-surface-phone never change a QuickShell file.
  • The adoption command clearly reports its plan and refuses unapproved replacements.
  • A deliberate profile adoption makes /agent, /resume, agent selection, and the Souveraine panel available against the locally running package service without importing another device's bar or dock.
  • An upgrade and uninstall preserve user settings and agent state.