Albert Armea 9c14fe5ccd Update documentation to reflect setup scripts

2026-01-01 13:50:48 -05:00

5.6 KiB

Raw Blame History

This prompt created the setup script ecosystem, including CI setup, dev setup, and end-user installation and configuration. It was provided to Claude Opus 4.5 via VSCode Agent mode.

The first draft was written by ChatGPT after some back-and-forth in this conversation.

The output was committed as fc0c1ce51d.

Task: Implement unified script system for dev, build, install, and user hardening

Objective

Implement a single, composable script system that:

Avoids duplication between CI, developer, and runtime workflows
Exposes clear, reversible primitives for build, install, and user hardening
Uses one authoritative entrypoint with subcommands
Allows CI, developers, and administrators to invoke the same logic with different scopes

The system must support:

CI build-only environments
Runtime-only systems
Developer systems (union of build + runtime deps)
Production installation and kiosk-style user hardening

High-level design constraints

One CLI entrypoint (script-based), with subcommands
Shared logic lives in libraries, not duplicated scripts
All tasks must be independently callable
All destructive actions must be reversible
Dependency sets must be defined once and derived programmatically
Shell scripts are acceptable and preferred for system integration

Required repository layout

scripts/
  shepherd              # main CLI dispatcher
  dev                   # thin wrapper → shepherd dev run
  admin                 # optional wrapper → shepherd admin ...

  lib/
    common.sh            # logging, error handling, sudo helpers
    deps.sh              # dependency set logic
    build.sh             # cargo build logic
    sway.sh              # nested sway execution helpers
    install.sh           # binary + config installation
    harden.sh            # harden / unharden user logic

  deps/
    build.pkgs           # build-only system packages
    run.pkgs             # runtime-only system packages
    dev.pkgs             # optional dev-only extras

No business logic should live in Makefile (if present).

CLI interface (must be implemented)

Dependency management

shepherd deps print build|run|dev
shepherd deps install build|run|dev

Behavior:

build = build.pkgs
run = run.pkgs
dev = union(build, run, dev.pkgs)
No duplicated lists anywhere

The build packages are currently listed in the CI definition (./.github/workflows/ci.yml). The CI definition should be updated to use this script for package management. You may leave a stub for the runtime packages that only includes sway.

You may assume Ubuntu 25.10 or higher. Warn but do not fail if the environment indicates otherwise.

Build

shepherd build            # debug build
shepherd build --release  # production build

Internals:

Wrap cargo build
Centralize binary names and target paths
No logic duplication in dev/run/install paths

Development run

shepherd dev run

This should be functionally equivalent to what is currently in ./run-dev and will serve as its replacement.

Behavior:

Builds (debug)
Launches nested sway
Executes built binaries with correct environment

This should reuse shared sway helpers (not inline logic).

Installation (composable steps)

Each step must be callable independently.

shepherd install bins [--prefix PREFIX]
shepherd install config --user USER [--source CONFIG]
shepherd install all --user USER [--prefix PREFIX]

Requirements:

Install release binaries to standard paths
Install our global Sway configuration to a standard path
Install desktop entry that tells the display manager to run shepherd-launcher via the Sway configuration (you will need to write this)
Support PREFIX and DESTDIR
Deploy example config to a specified user
Do not assume hardening is enabled

User hardening (reversible)

shepherd harden apply  --user USER
shepherd harden revert --user USER

Requirements:

Harden a user so it can only run shepherd-launcher
Support reverting to original system state
Persist rollback state under:
```
/var/lib/shepherdd/hardening/<user>/
```
Hardening and unharden must be idempotent

No assumptions about display manager; logic should be isolated.

Shared library responsibilities

`lib/common.sh`

Logging (info, warn, error)
require_root, maybe_sudo
Safe command execution helpers

`lib/deps.sh`

Read package lists
Compute unions
Install or print packages

`lib/build.sh`

Cargo build abstraction
Debug vs release handling
Binary discovery

`lib/sway.sh`

Nested sway environment setup
Command execution inside sway
Shared by dev and production paths

`lib/install.sh`

Binary install logic
Config deployment logic

`lib/harden.sh`

Apply hardening
Revert hardening
Track system state changes

Wrapper scripts

./run-dev → exec ./scripts/shepherd dev run
Optional Makefile targets may call shepherd, but must contain no logic

Non-goals

No Docker/Nix/devcontainer required
No GUI tooling
No distro-specific packaging beyond apt-style package lists
No Rust rewrite of scripts unless strictly necessary

Acceptance criteria

CI can install only build deps and run shepherd build
Runtime system can install only run deps
Developer can install dev deps and run ./run-dev
Admin can:
- install binaries
- deploy config
- harden and unharden a user safely
No duplicated dependency lists
No duplicated build or sway logic

5.6 KiB Raw Blame History