104 lines
5.2 KiB
Markdown
104 lines
5.2 KiB
Markdown
---
|
|
task_id: souveraine-surface-001
|
|
title: QuickShell surface package — explicit, reversible desktop adoption
|
|
status: in_progress
|
|
priority: high
|
|
phase: delivery
|
|
created: 2026-07-13
|
|
references: 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
|
|
|
|
- [x] Expose `deploy.sh --manifest` so package tooling and the developer path
|
|
share a single authoritative list of managed files.
|
|
- [x] 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.
|