Skip to content

feat: printer CLI, GitHub releases, one-line install and self-update - #4

Merged
DavidGodefroid merged 4 commits into
mainfrom
feat/cli-release-tooling
Nov 6, 2026
Merged

DavidGodefroid merged 4 commits into
mainfrom
feat/cli-release-tooling

Conversation

@DavidGodefroid

Copy link
Copy Markdown
Member

Objectif

Faire de l'agent d'impression un outil simple à exploiter sur le PC de caisse : binaire publié sur GitHub, installation en une commande sans Go, service en arrière-plan qui démarre au boot, et une commande printer pour tout gérer (état, logs, config, mise à jour avec rollback).

Choix de conception

  • Un seul binaire printer (sous-commandes Go, pas de script wrapper) : l'agent (printer run, lancé par systemd) et les commandes d'exploitation dans le même fichier. Une seule chose à télécharger et à vérifier, update remplace tout d'un coup, et la logique (versions, checksum, rollback, validation de la config) est testée en Go plutôt que dans du bash. Toutes les anciennes sous-commandes (detect, receipt-test, label…) restent.
  • systemd utilisateur + linger conservés : pas besoin de root, le terminal n'a pas à rester ouvert, démarrage au boot sans session ouverte. Le service garde le même nom (print-agent.service) et la même config (~/.config/print-agent/env) : migration sans casse, historique journald conservé. StartLimitIntervalSec=0 pour qu'il ne renonce jamais (réseau absent au boot).
  • Unités systemd, modèle de config et scripts Python d'étiquettes embarqués dans le binaire (assets.go). Les scripts sont extraits au besoin dans ~/.cache/print-agent/scripts/<hash>/, ce qui permet d'imprimer des étiquettes avec un binaire de release, sans clone du dépôt. Ordre de recherche inchangé : LABEL_SCRIPT_PATH/STICKER_SCRIPT_PATH, puis scripts/ à côté du binaire, puis la copie embarquée.
  • printer update : releases/latest → comparaison semver (un build de dev est toujours remplacé) → téléchargement de printer_linux_<arch> + checksums.txt → vérification sha256 → exécution du nouveau binaire (version --short doit renvoyer le tag) → rename atomique, l'ancien est gardé en printer.prev → redémarrage → le service doit rester active pendant 20 s sans redémarrage automatique (NRestarts / auto-restart) → sinon rollback et redémarrage de l'ancien. Un verrou flock empêche deux mises à jour simultanées. printer rollback échange printer et printer.prev.
  • Mise à jour automatique livrée mais désactivée par défaut (printer autoupdate on|off|status) : timer quotidien à 05:00 (+30 min aléatoires), non persistent, pour ne jamais mettre à jour un PC allumé en pleine ouverture. Raison : une mise à jour redémarre l'agent, et une caisse doit changer de version quand on l'a décidé.
  • Release : workflow GitHub Actions simple (pas de GoReleaser, pas de config en plus) : vet + tests, build statique linux/amd64 et linux/arm64 (CGO_ENABLED=0, -ldflags -X main.version/commit/date), checksums.txt, gh release create --generate-notes. Un tag -rc.N produit une pré-release, ignorée par update. Un workflow CI (vet, tests, build, bash -n install.sh) tourne aussi sur les PR et sur main.
  • Dépôt public (vérifié : visibility: PUBLIC), donc rien n'est requis. S'il devient privé : install.sh bascule sur gh release download, et update lit PRINTER_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN (environnement ou config), puis le token de gh.
  • printer setup n'active le service au boot qu'une fois la config valide (sinon boucle de crash toutes les 5 s à chaque démarrage) ; printer config edit l'active et le redémarre après validation.

Commandes

printer status · start / stop / restart (refusent une config invalide, vérifient que l'agent reste démarré) · log (suivi en temps réel ; -n N pour les N dernières lignes, -f, --since, --errors) · update [--check] [--version vX.Y.Z] · rollback · version [--short] · config [show|edit|check|path] (secrets masqués, validation : format EnvironmentFile, champs requis, valeurs d'exemple, URL, durées, variables inconnues) · test (ticket « TEST IMPRESSION » sur l'imprimante ticket : version, poste, date, device ; sans prix, sans code-barres, sans ouverture du tiroir) · autoupdate [on|off|status] · setup [--no-start].

Installation sur un PC neuf

# en tant qu'utilisateur de la caisse, pas root
curl -fsSL https://raw.githubusercontent.com/ICTools/printer-agent/main/deploy/install.sh | bash
printer config edit     # PRINT_AGENT_API_URL / _KEY / _SECRET, puis redémarrage automatique
printer status
printer test

Pré-requis inchangés : groupe lp (sudo usermod -aG lp $USER), python3-pil et brother_ql pour les étiquettes. setup vérifie ces points et l'affiche.

Migration du PC de caisse actuel

(installé avec l'ancien install.sh : ~/.local/bin/print-agent et le service print-agent)

cp ~/.config/print-agent/env ~/print-agent-env.backup
curl -fsSL https://raw.githubusercontent.com/ICTools/printer-agent/main/deploy/install.sh | bash
printer status          # attendu : active (running), Config OK, linger on
printer test

Ce que fait setup : garde ~/.config/print-agent/env tel quel (droits passés à 600), réécrit print-agent.service avec ExecStart=%h/.local/bin/printer run, déplace l'ancien binaire en ~/.local/bin/print-agent.legacy et le remplace par un lien print-agent -> printer, puis redémarre. Retour arrière documenté dans le README (remettre print-agent.legacy et l'ancien ExecStart).

À faire après le merge, avant la migration : publier la première release (le script télécharge releases/latest).

Première release

Après le merge sur main :

git checkout main && git pull
git tag -a v1.0.0 -m "v1.0.0"
git push origin v1.0.0

Le workflow Release publie printer_linux_amd64, printer_linux_arm64 et checksums.txt. Vérification : gh release view v1.0.0 -R ICTools/printer-agent.

Tests

  • go vet ./... et go test ./... passent.
  • Nouveaux tests unitaires : comparaison de versions (semver, pré-releases, builds de dev / git describe), parsing de checksums.txt et vérification sha256, sélection d'asset, Stage contre un faux GitHub (binaire modifié refusé, URL API utilisée avec un token), Swap/Rollback, verrou, détection de boucle de crash systemd, parsing / validation / masquage de la config, migration de l'ancien binaire, config jamais écrasée, extraction des scripts embarqués, ticket de test sans ouverture du tiroir.
  • Testé à la main dans un HOME isolé avec de faux systemctl/loginctl et un faux serveur GitHub local : migration depuis une ancienne installation, mise à jour v0.1.0 → v0.2.0, rollback automatique quand le service redémarre en boucle, checksum modifié refusé sans rien installer, printer rollback. Build linux/arm64 vérifié.
  • Pas encore testé : le vrai workflow de release (il tournera au premier tag) et une installation sur le vrai PC de caisse.

🤖 Generated with Claude Code

DavidGodefroid and others added 4 commits November 6, 2026 11:22
…pdate

- rename cmd/print-agent to cmd/printer; the binary keeps every agent and
  printing subcommand and adds status, start/stop/restart, log, update,
  rollback, version, config (show/edit/check/path), test, autoupdate, setup
- update: GitHub latest release, semver comparison, sha256 check against
  checksums.txt, probe of the new binary, atomic rename keeping printer.prev,
  restart and rollback when the service does not stay up
- setup: idempotent install of the binary, systemd user units, config
  template (never overwrites), linger; migrates the old print-agent binary
- embed the units, the config template and the label scripts in the binary
- install.sh downloads and verifies the release binary (gh fallback for a
  private repository), --from-source keeps the local Go build

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tion)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- labels: use LABEL_SCRIPT_PATH/STICKER_SCRIPT_PATH only when the file
  exists (warn and fall back to the embedded copy); embed sticker.png and
  extract it next to print.py; config check/setup warn on missing paths
- envfile: never echo a malformed line (it may hold a secret); mask
  user:pass@ in URLs
- update: https-only downloads to GitHub hosts (redirects included, test
  override PRINTER_UPDATE_INSECURE=1), 100 MB limit, remember a version
  rolled back by the health check so the timer does not reinstall it,
  explicit downgrade message; lock also rollback and setup; setup keeps
  printer.prev when the same build is already installed
- linger: fall back to $USER / id -un when user.Current fails
- install.sh: run from main() (no partial curl|bash), temp dir under
  ~/.cache (noexec /tmp), setup with stdin from /dev/null
- release workflow: tag must be on main, concurrency, actions pinned by SHA
- tests: installAndRestart rollback orchestration, no secret in problems

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DavidGodefroid

Copy link
Copy Markdown
Member Author

Retours de revue corrigés dans 3eeeca2 :

Bloquants

  1. Étiquettes après migration : LABEL_SCRIPT_PATH / STICKER_SCRIPT_PATH ne sont utilisées que si le fichier existe. Sinon l'agent écrit un warning et prend la copie embarquée. printer config check et printer setup signalent un chemin absent. Le README demande de retirer ces lignes avant de supprimer le clone (avec un grep dans la procédure de migration).
  2. sticker.png est embarqué et extrait dans le même dossier haché que print.py et print_sticker.py. Un test vérifie le contenu des trois fichiers extraits.
  3. Fuite de secret : une ligne malformée n'est plus recopiée (seulement le numéro de ligne). Un test vérifie qu'aucun message ne contient la valeur.

Mineurs

  • install.sh :

    • tout le script tourne dans main(), appelé à la dernière ligne ;
    • dossier temporaire sous ~/.cache (pas /tmp, qui peut être noexec) ;
    • setup </dev/null ;
    • usage() n'utilise plus $0.
  • setup ne remplace plus printer.prev si le même binaire est déjà installé.

  • Verrou aussi pour rollback et setup.

  • Une version annulée par le rollback automatique est mémorisée (~/.local/bin/.printer-refused-version). update et le timer ne la réinstallent plus. Une version plus récente passe normalement, et --version la force.

  • Téléchargements :

    • https uniquement, vers github.com, api.github.com et *.githubusercontent.com, redirections comprises (ou vers l'hôte de PRINTER_GITHUB_API s'il est en https) ;
    • PRINTER_UPDATE_INSECURE=1 lève ces contrôles, pour un serveur de test local seulement ;
    • taille limitée à 100 Mo.
  • update --version <ancienne> annonce un « downgrade ».

  • Linger : si user.Current() échoue, repli sur $USER puis id -un, avec un message clair si tout échoue.

  • Les identifiants user:pass@ sont masqués dans PRINT_AGENT_API_URL (config show, status).

  • Workflow release :

    • refuse un tag dont le commit n'est pas sur main ;
    • concurrency ;
    • actions épinglées par SHA (checkout v7.0.1, setup-go v7.0.0, aussi dans la CI).
  • Tests ajoutés pour installAndRestart :

    • mise à jour saine conservée ;
    • rollback quand le nouveau binaire redémarre en boucle, avec la version refusée mémorisée ;
    • cas où l'ancien binaire échoue aussi.

    Aussi : describeExplicit, refus d'une URL non https ou d'un hôte inconnu, limite de taille.

Vérifications : go vet ./..., go test -race ./... et les builds CGO_ENABLED=0 amd64 et arm64 passent. bash -n install.sh passe aussi. install.sh --from-source a été testé dans un HOME isolé avec un faux systemctl.

@DavidGodefroid
DavidGodefroid merged commit 3a15765 into main Nov 6, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant