Instalace Majordomus

Rychlá instalace

curl -fsSL https://majordomus.dev/install.sh | sh

Poté v repozitáři, který chcete dozorovat:

majordomus init

init přidá, co vrstva potřebuje, a to, co repozitář už má, nechá být. Jedinou výjimkou je README.md, která nezmiňuje AGENTS.md: init připojí krátký odstavec, který ho jmenuje, protože doctor selže u README, které čtenáře nedovede k zaváděcímu souboru agenta. init vypíše odstavec spolu se vším ostatním, co vytvořilo. Nevytváří README tam, kde žádné není, a osobní vrstva README projektu nechává být.

Nainstalovat a inicializovat jedním příkazem

curl -fsSL https://majordomus.dev/install.sh | sh -s -- --init

--init spustí majordomus init v aktuálním adresáři pomocí právě nainstalovaného spustitelného souboru, jeho absolutní cestou, takže nezávisí na tom, zda byl váš PATH znovu načten. Pokud instalace uspěje a inicializace selže, instalátor to řekne těmito slovy a funkční instalaci ponechá.

Osobní režim

curl -fsSL https://majordomus.dev/install.sh | sh -s -- --personal

Pro používání nástroje jako vlastního v repozitáři, který sdílejí jiní: váš tým, klient, open-source projekt. --personal spustí majordomus init --personal v aktuálním adresáři. Vytvoří stejnou vrstvu jako prostý init a nezmění nic, co repozitář sdílí.

• Žádný sledovaný soubor se nemění a nic se nepřidává do .gitignore. Vrstva je pokryta označeným blokem v info/exclude v adresáři gitu, tedy v souboru, který git nikdy necommituje, nepushuje ani neklonuje.
• majordomus init --personal čte git status před zápisem a skončí exitem 10, pokud potom nečte totéž. Instalátor pak sám znovu porovná stav a vypíše Verified (personal).
• majordomus update a majordomus capture install pokryjí každý soubor před zápisem a soubor, který projekt už sleduje, nechají být. majordomus doctor ověřuje pokrytí znovu při každém běhu.
• Vrstva patří tomuto checkoutu. Necestuje s klonem, pushem ani stashem.

Když zkouška prokázala svou věc, předejte vrstvu týmu:

majordomus init --extend --shared

Odstraní krytí, přidá dva řádky .gitignore, které přidá obyčejný init, a vypíše, co je nyní třeba commitnout v repozitáři. Nic necommituje; ten krok je váš. Soubor, který je už svým jménem něčí osobní, například CLAUDE.local.md, zůstává kryt a zůstává váš.

Chcete-li místo toho skončit, smažte blok mezi # >>> majordomus personal >>> a # <<< majordomus personal <<< a soubory, které uvádí.

Osobní režim drží vrstvu stranou od toho, co repozitář sdílí. Není to řízení přístupu ani způsob, jak obejít pravidla organizace o nástrojích. Rozhodnutí je ADR 0145; PERSONAL_MODE.md je celý výklad: k čemu je, co zůstává viditelné a cesta od osobní vrstvy ke sdílené.

Ověřit

majordomus --version
majordomus doctor

doctor hlásí, zda se vrstva rozlišuje, zda je každé vynucování, které si nárokuje, skutečně zapojeno a které řádky hooků stále chybí.

Co dělá s vaším strojem

Nic mimo dvě místa a nikdy jako root:

$HOME/.local/share/majordomus/versions/<version>/    the release, unpacked
$HOME/.local/bin/majordomus                    a launcher
$HOME/.local/bin/majordomus-mcp                a launcher for the MCP server

Launchery jsou dvouřádkové shellové skripty, které přes exec spouštějí verzovaný strom. Žádný profil shellu se neupravuje, žádný správce balíčků se nevolá a sudo se nikdy nespouští: pokud adresář není zapisovatelný, instalátor řekne který, a skončí.

Podporované platformy

Tato tabulka je generována z share/distribution.yaml, jediného místa, kde se platforma deklaruje. Instalátor vyřeší váš stroj na její řádek z uname -s, uname -m a na Linuxu z C knihovny, kterou najde; matice release buildů se generuje ze stejných řádků, takže platforma uvedená zde je platforma, kterou release skutečně sestavil.

Windows x86_64 (x86_64-pc-windows-msvc) — Příkaz, který člověk spouští, je bash: bin/majordomus a lib/*.sh jsou POSIX shell a archiv je nese vedle spustitelného souboru. Dokud tato polovina nemá odpověď pro Windows, publikace archivu pro Windows by dodala spustitelný soubor, který nic nemůže řídit.

Volba, kam to půjde

curl -fsSL https://majordomus.dev/install.sh | sh -s -- --install-dir "$HOME/bin"
curl -fsSL https://majordomus.dev/install.sh | sh -s -- --prefix "$HOME/opt/majordomus"

nebo, ekvivalentně:

MAJORDOMUS_INSTALL_DIR="$HOME/bin" curl -fsSL https://majordomus.dev/install.sh | sh

Připnutí verze

curl -fsSL https://majordomus.dev/install.sh | sh -s -- --version v0.30.2

Připnutá instalace rozlišuje https://majordomus.dev/releases/v0.30.2.json, který jmenuje přesný artefakt a jeho digest sha256, a proto pokaždé nainstaluje stejné bajty. Nepřipnutá instalace rozlišuje https://majordomus.dev/releases/latest.json, tedy poslední stabilní release, který se posouvá, jak se publikují další. V CI používejte připnutou podobu.

Použití v CI

curl -fsSL https://majordomus.dev/install.sh | sh -s -- --version v0.30.2
export PATH="$HOME/.local/bin:$PATH"
majordomus --version

Instalátor nevyžaduje žádnou interakci a na nic se neptá: vše, co dělá, je dáno jeho argumenty a prostředím. Připněte verzi, aby nový release nemohl změnit sestavení, které dřív procházelo.

Aktualizace a přeinstalace

Spusťte stejný příkaz znovu. Instalátor je idempotentní:

• tatáž verze je už nainstalována — řekne to a skončí s 0;
• nainstalována starší verze — upgraduje se a předchozí instalace funguje až do okamžiku, kdy se launcher nahradí;
• nainstalována novější verze a žádná nepřipnutá — odmítne vás vrátit zpět a řekne, jak to přesto udělat (--force nebo --version).

Odinstalace

rm -f $HOME/.local/bin/majordomus $HOME/.local/bin/majordomus-mcp
rm -rf $HOME/.local/share/majordomus

To je vše. Odstraní nástroj. Neodstraní adresář .ai/ žádného repozitáře: vaše politika, pravidla, rozhodnutí, plán a historie patří repozitáři, ne nástroji, a žádný příkaz tohoto projektu je nemaže.

Releasy

Každý release publikuje jeden archiv pro každý podporovaný cíl plus soubor SHA256SUMS a jeho metadata se servírují jako JSON vedle instalátoru. Instalátor řeší release z onoho JSONu, nikdy z API ani HTML GitHubu, takže změna stránek GitHubu nemůže rozbít instalaci. Jediné volání GitHubu, které může provést, je volitelná kontrola provenience níže, přes GitHub CLI.

Bezpečnostní model

Co je chráněno a jak:

• Metadata se stahují přes HTTPS s přesměrováními omezenými na HTTPS. Základní URL, která není HTTPS, se odmítne, ledaže dvě explicitní proměnné prostředí říkají jinak, což existuje proto, aby testy samotného instalátoru mohly poskytovat fixtures.
• Artefakt se ověřuje před rozbalením. Metadata nesou digest sha256 a velikost; instalátor zkontroluje obojí a při neshodě stažení zahodí a skončí. Žádné „varovat a pokračovat“ neexistuje.
• URL artefaktu se kontroluje proti hostiteli vydání vlastního projektu, než se z něj cokoli stáhne, a každá hodnota přečtená z metadat se porovná s tvarem, který musí mít. Nic přečtené po síti se nedostane do příkazové řádky, cesty ani shellu.
• Archiv se před rozbalením zkontroluje. Absolutní cesty, průchod .., symbolické a pevné odkazy, zařízení a každá položka mimo vlastní adresář archivu se zamítnou jménem a nic se nerozbalí.
• Instalace je atomická. Nový strom se rozbalí vedle starého a jeho spustitelný soubor se jednou spustí z dočasného umístění, aby se dokázalo, že hlásí verzi, která byla vyřešena. Teprve potom se launcher nahradí přejmenováním. Jakékoli selhání před tím nechá předchozí instalaci přesně tak, jak byla.
• Nic se nepovyšuje. sudo se v instalátoru nevyskytuje nikde.

Čemu se dál důvěřuje: GitHub Pages obsluhují metadata, GitHub Releases obsluhují artefakty a release pipeline vytvořila obojí. Kontrolní součty vážou artefakt k metadatům; samy neprokazují, kdo metadata napsal. K tomu slouží provenance: každý archiv releasu od v0.20.0 je atestován release workflow (dřívější nesou jen kontrolní součty) a kde je GitHub CLI nainstalováno a přihlášeno, instalátor se jej zeptá, zda byl tento archiv sestaven workflow tohoto repozitáře. Závěrečný report říká, které z toho ověřil — provenance (…) and checksum, nebo checksum only s důvodem. MAJORDOMUS_REQUIRE_PROVENANCE=1 neinstaluje nic bez ověřené provenance. Ručně: gh attestation verify <archive> --repo <repository>. Co která cesta ověřuje, je v docs/DISTRIBUTION.md.

Přečíst před spuštěním

curl … | sh spouští skript, který jste nečetli. Pokud ho raději přečtete nejdřív:

curl -fsSL https://majordomus.dev/install.sh -o install-majordomus.sh
less install-majordomus.sh
sh install-majordomus.sh

Instalátor je jeden soubor bez závislostí kromě curl nebo wget, tar a jednoho z sha256sum nebo openssl. Jeho horní polovina se generuje z distribučního modelu a spodní polovina je chování; obojí se reviduje v tomto repozitáři a v CI lintuje shellcheck.

Řešení problémů

majordomus: command not found po instalaci. Adresář launcheru není ve vašem PATH. Instalátor vypíše přesný řádek k přidání; váš shellový profil neupravuje.

„does not provide a prebuilt binary for“. Váš stroj se nerozřešil na žádný podporovaný cíl. Zpráva pojmenovává, co bylo zjištěno, a vypisuje, co je podporováno. Neexistuje automatický návrat k sestavení ze zdroje: to by vyžadovalo toolchain, jehož nevyžadování tento instalátor slibuje.

„the downloaded archive does not match its digest“. Zastavte. Nic nebylo nainstalováno. Spusťte to znovu; pokud se to stane dvakrát, je špatný artefakt nebo metadata a vynucení by bylo špatnou reakcí.

Za proxy. curl a wget čtou obvyklé prostředí https_proxy; instalátor nepřidává nic vlastního.

Vidět, co by udělal.

curl -fsSL https://majordomus.dev/install.sh | sh -s -- --dry-run
curl -fsSL https://majordomus.dev/install.sh | sh -s -- --verbose

--dry-run rozliší platformu, release a každou cestu, vypíše je a nic nemění.

Sestavení ze zdroje

Pro přispěvatele, ne pro instalaci. Vlastní nástroje repozitáře jsou zdokumentovány v CONTRIBUTING.md:

git clone https://github.com/korczis/prismatic-majordomus majordomus
cd majordomus
cargo build --release --manifest-path apps/majordomus-cli/Cargo.toml

Shellový nástroj nepotřebuje žádný build: bin/majordomus běží z checkoutu. Pro všechno ostatní použijte instalátor — zdrojový checkout je vývojové prostředí, ne instalace.

Jak to funguje pod povrchem

Architektura, cesta důvěry, postup release a jak přidat platformu jsou v DISTRIBUTION.md.