Skip to content

Commit c6f1769

Browse files
committed
chore(toolchain): sync agentic maintenance baseline
1 parent 4ca2bba commit c6f1769

9 files changed

Lines changed: 1928 additions & 0 deletions
Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# maintain-agentic-brew-apps(1)
2+
3+
## Name
4+
5+
`maintain-agentic-brew-apps` - pflegt die Homebrew-/apt-Toolchain fuer agentische Entwicklung
6+
7+
*maintains the Homebrew/apt toolchain for agentic development*
8+
9+
## Synopsis
10+
11+
```bash
12+
bash scripts/maintain-agentic-brew-apps.sh [--dry-run] [--compare-only] [--skip-upgrade] [--skip-vscode-extensions] [--include-optional] [--npm-agent-registry PATH]
13+
```
14+
15+
## Beschreibung / Description
16+
17+
Das Werkzeug liest
18+
`scripts/config/brew-apps-registry.json` und gleicht die lokale macOS-/Linux-
19+
Toolchain fuer agentische Entwicklung ab. Zusaetzlich liest es
20+
`scripts/config/vscode-extensions-registry.json` und pflegt die Required-VS-
21+
Code-Extensions fuer die sechs MSL-Pfade C#, Go, Java, Python, Rust und Swift
22+
sowie Microsoft Container Tools fuer Podman-Workflows. Danach liest es
23+
`scripts/config/required-cli-tools-registry.json` und prueft die Required-CLI-
24+
Tools fuer die sechs MSL-Pfade, `syft`, GitHub Spec Kit (`specify`) und die
25+
Agenten-CLIs `codex`, `claude`, `agy` und `copilot`. npm-basierte
26+
Fallbacks fuer Codex, Claude und Copilot werden ueber
27+
`scripts/config/npm-agent-cli-registry.json` installiert, wenn ihre CLI fehlt.
28+
Auf Systemen mit Homebrew fuehrt ein normaler Lauf `brew update`,
29+
`brew upgrade` und die Installation fehlender Required-Formulae aus. Auf macOS
30+
werden zusaetzlich Required-Casks gepflegt.
31+
Fehlt `agy` auf Linux, wird der offizielle Installer nur nach erfolgreicher
32+
SHA-256-Pruefung gegen die Required-CLI-Registry ausgefuehrt.
33+
CLI-Versionsproben werden nach fuenf Sekunden beendet, damit interaktive oder
34+
festhaengende Agenten-CLIs den Wartungslauf nicht blockieren.
35+
Ein bereits vorhandenes App-Bundle fuer Visual Studio Code unter
36+
`/Applications/Visual Studio Code.app` oder `~/Applications/Visual Studio Code.app`
37+
gilt als erfuellter Required-Cask, auch wenn VS Code nicht von Homebrew
38+
installiert wurde.
39+
40+
*The tool reads `scripts/config/brew-apps-registry.json` and reconciles the
41+
local macOS/Linux toolchain for agentic development. It additionally reads
42+
`scripts/config/vscode-extensions-registry.json` and maintains the required VS
43+
Code extensions for the six MSL paths C#, Go, Java, Python, Rust, and Swift
44+
plus Microsoft Container Tools for Podman workflows. It then reads
45+
`scripts/config/required-cli-tools-registry.json` and checks the required CLI
46+
tools for the six MSL paths, `syft`, GitHub Spec Kit (`specify`), and the
47+
agent CLIs `codex`, `claude`, `agy`, and `copilot`. npm-based fallbacks for Codex, Claude, and Copilot are installed from
48+
`scripts/config/npm-agent-cli-registry.json` when their CLI is missing. On
49+
systems with Homebrew, a normal run executes `brew update`, `brew upgrade`, and
50+
installs missing required formulae. On macOS it also maintains required casks.
51+
When `agy` is missing on Linux, the official installer runs only after its
52+
SHA-256 digest matches the required CLI registry.
53+
CLI version probes stop after five seconds so interactive or stuck agent CLIs
54+
cannot block maintenance.
55+
An existing Visual Studio Code app bundle under `/Applications/Visual Studio Code.app`
56+
or `~/Applications/Visual Studio Code.app` satisfies the required cask even when
57+
VS Code was not installed by Homebrew.*
58+
59+
Wenn Linux kein `brew`, aber `apt` bereitstellt, nutzt das Skript den explizit
60+
dokumentierten apt-Fallback aus der Registry: `sudo apt update`,
61+
`sudo apt upgrade` und nur die dort gemappten Pakete. `code` und `helix` werden
62+
im apt-Fallback nur installiert, wenn sie in den bereits konfigurierten apt-
63+
Quellen verfuegbar sind. Die Homebrew-Registry enthaelt Top-Level-Pakete
64+
(`brew leaves --installed-on-request`) und macOS-Casks, keine transitiven
65+
Abhaengigkeiten. `xquartz` ist bewusst ausgeschlossen.
66+
67+
*When Linux has no `brew` but provides `apt`, the script uses the explicitly
68+
documented apt fallback from the registry: `sudo apt update`,
69+
`sudo apt upgrade`, and only the mapped packages. In the apt fallback, `code`
70+
and `helix` are installed only when available from the already configured apt
71+
sources. The Homebrew registry contains top-level packages
72+
(`brew leaves --installed-on-request`) and macOS casks, not transitive
73+
dependencies. `xquartz` is intentionally excluded.*
74+
75+
## Optionen / Options
76+
77+
| Option | Bedeutung / Meaning |
78+
|---|---|
79+
| `--dry-run` | Paketmanager-Aktionen anzeigen, nicht ausfuehren |
80+
| `--compare-only` | Registry-Drift nach Required/Optional getrennt melden, nichts installieren oder upgraden |
81+
| `--registry PATH` | Alternative Registry-Datei verwenden |
82+
| `--vscode-registry PATH` | Alternative VS-Code-Extension-Registry verwenden |
83+
| `--npm-agent-registry PATH` | Alternative npm-Agent-CLI-Registry verwenden |
84+
| `--skip-upgrade` | `brew update`/`brew upgrade` bzw. apt-Update/Upgrade ueberspringen |
85+
| `--skip-vscode-extensions` | VS-Code-Extensions weder installieren noch vergleichen |
86+
| `--include-optional` | Auch optionale Registry-Eintraege installieren |
87+
| `-h`, `--help` | Hilfe anzeigen |
88+
89+
## Beispiele / Examples
90+
91+
```bash
92+
bash scripts/maintain-agentic-brew-apps.sh --dry-run
93+
bash scripts/maintain-agentic-brew-apps.sh --compare-only
94+
bash scripts/maintain-agentic-brew-apps.sh
95+
```
96+
97+
## Abschlusskriterien / Closeout Criteria
98+
99+
- `gitleaks version` funktioniert.
100+
- `syft version` und `specify --version` funktionieren.
101+
- `codex --version`, `claude --version`, `agy --version` und
102+
`copilot --help` funktionieren.
103+
- `.NET`, Go, Java/Javac, Python, Rust/Cargo und Swift sind per CLI pruefbar,
104+
soweit die Plattform den jeweiligen Pfad unterstuetzt.
105+
- `code --version` und `hx --version` funktionieren, sofern die Plattform die grafische bzw. TUI-Editor-Basis installieren konnte.
106+
- `--compare-only` meldet `missing_on_machine.required.*: none`.
107+
- `python3 -m json.tool scripts/config/brew-apps-registry.json` ist erfolgreich.
108+
- `python3 -m json.tool scripts/config/vscode-extensions-registry.json` ist erfolgreich.
109+
- `python3 -m json.tool scripts/config/required-cli-tools-registry.json` ist erfolgreich.
110+
- `python3 -m json.tool scripts/config/npm-agent-cli-registry.json` ist erfolgreich.
111+
- Neue bewusst installierte Top-Level-Tools werden in der Registry nachgetragen.
112+
113+
*`gitleaks version`, `syft version`, `specify --version`, `codex --version`,
114+
`claude --version`, `agy --version`, and `copilot --help` work; .NET,
115+
Go, Java/Javac, Python, Rust/Cargo, and Swift are CLI-checkable where the
116+
platform supports the path; `code --version` and `hx --version` work where the
117+
platform could install the graphical/TUI editor baseline; `--compare-only`
118+
reports `missing_on_machine.required.*: none`; the registries are valid JSON;
119+
and intentional new top-level tools are added to the registry.*
120+
121+
## Sicherheit / Security
122+
123+
Die Registry enthaelt nur Paketnamen und Zwecke, keine Secrets, lokalen Tokens
124+
oder privaten Pfade. Paketmanager-Laeufe schreiben ausserhalb des Repositories
125+
und sollen vorab mit `--dry-run` geprueft werden.
126+
127+
*The registry contains only package names and purposes, not secrets, local
128+
tokens, or private paths. Package-manager runs write outside the repository and
129+
should be previewed with `--dry-run` first.*
Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# maintain-agentic-winget-apps(1)
2+
3+
## Name
4+
5+
`maintain-agentic-winget-apps` - pflegt die WinGet-Toolchain fuer agentische Entwicklung
6+
7+
*maintains the WinGet toolchain for agentic development*
8+
9+
## Synopsis
10+
11+
```powershell
12+
pwsh -NoProfile -File scripts/maintain-agentic-winget-apps.ps1 [-WhatIf] [-CompareOnly] [-SkipUpgrade] [-SkipVSCodeExtensions] [-IncludeOptional] [-NpmAgentRegistry PATH]
13+
```
14+
15+
## Beschreibung / Description
16+
17+
Das Werkzeug liest
18+
`scripts/config/winget-apps-registry.json` und gleicht die Windows-Toolchain fuer
19+
agentische Entwicklung ab. Zusaetzlich liest es
20+
`scripts/config/vscode-extensions-registry.json` und pflegt die Required-VS-
21+
Code-Extensions fuer die sechs MSL-Pfade C#, Go, Java, Python, Rust und Swift
22+
sowie Microsoft Container Tools fuer Podman-Workflows. Danach liest es
23+
`scripts/config/required-cli-tools-registry.json` und prueft die Required-CLI-
24+
Tools fuer die sechs MSL-Pfade, `syft`, GitHub Spec Kit (`specify`) und die
25+
Agenten-CLIs `codex`, `claude` und `copilot` sowie das Required-Paket
26+
`Google.AntigravityCLI`. npm-basierte Fallbacks fuer Codex, Claude und Copilot werden ueber
27+
`scripts/config/npm-agent-cli-registry.json` installiert, wenn ihre CLI fehlt.
28+
Ein normaler Lauf aktualisiert WinGet-Quellen, fuehrt `winget upgrade --all`
29+
aus und installiert fehlende Required-Pakete per `winget install --id <Id>
30+
--exact`.
31+
CLI-Versionsproben werden nach fuenf Sekunden beendet, damit interaktive oder
32+
festhaengende Agenten-CLIs den Wartungslauf nicht blockieren.
33+
34+
*The tool reads `scripts/config/winget-apps-registry.json` and reconciles the
35+
Windows toolchain for agentic development. It additionally reads
36+
`scripts/config/vscode-extensions-registry.json` and maintains the required VS
37+
Code extensions for the six MSL paths C#, Go, Java, Python, Rust, and Swift
38+
plus Microsoft Container Tools for Podman workflows. It then reads
39+
`scripts/config/required-cli-tools-registry.json` and checks the required CLI
40+
tools for the six MSL paths, `syft`, GitHub Spec Kit (`specify`), and the
41+
agent CLIs `codex`, `claude`, and `copilot` plus required package `Google.AntigravityCLI`. npm-based fallbacks for Codex, Claude, and Copilot are installed from
42+
`scripts/config/npm-agent-cli-registry.json` when their CLI is missing. A
43+
normal run refreshes WinGet sources, runs `winget upgrade --all`, and installs
44+
missing required packages via `winget install --id <Id> --exact`. CLI version
45+
probes stop after five seconds so interactive or stuck agent CLIs cannot block
46+
maintenance.*
47+
48+
Das Skript versucht zuerst `winget update`. Wenn diese Unterfunktion auf der
49+
installierten WinGet-Version nicht verfuegbar ist, nutzt es
50+
`winget source update` als kompatiblen Fallback. Paket-IDs werden vor der
51+
Installation mit `winget search --id <Id> --exact` geprueft.
52+
53+
*The script tries `winget update` first. If that subcommand is not available on
54+
the installed WinGet version, it uses `winget source update` as a compatible
55+
fallback. Package IDs are checked with `winget search --id <Id> --exact` before
56+
installation.*
57+
58+
## Optionen / Options
59+
60+
| Option | Bedeutung / Meaning |
61+
|---|---|
62+
| `-WhatIf` | Paketmanager-Aktionen anzeigen, nicht ausfuehren |
63+
| `-CompareOnly` | Nur Registry-Drift melden, nichts installieren oder upgraden |
64+
| `-Registry PATH` | Alternative Registry-Datei verwenden |
65+
| `-VSCodeRegistry PATH` | Alternative VS-Code-Extension-Registry verwenden |
66+
| `-NpmAgentRegistry PATH` | Alternative npm-Agent-CLI-Registry verwenden |
67+
| `-SkipUpgrade` | WinGet-Update und `winget upgrade --all` ueberspringen |
68+
| `-SkipVSCodeExtensions` | VS-Code-Extensions weder installieren noch vergleichen |
69+
| `-IncludeOptional` | Auch optionale Registry-Eintraege installieren |
70+
71+
## Beispiele / Examples
72+
73+
```powershell
74+
pwsh -NoProfile -File scripts/maintain-agentic-winget-apps.ps1 -WhatIf
75+
pwsh -NoProfile -File scripts/maintain-agentic-winget-apps.ps1 -CompareOnly
76+
pwsh -NoProfile -File scripts/maintain-agentic-winget-apps.ps1
77+
```
78+
79+
## Abschlusskriterien / Closeout Criteria
80+
81+
- `gitleaks version` funktioniert.
82+
- `syft version` und `specify --version` funktionieren.
83+
- `codex --version`, `claude --version`, `agy --version` und
84+
`copilot --help` funktionieren.
85+
- `.NET`, Go, Java/Javac, Python, Rust/Cargo und Swift sind per CLI pruefbar.
86+
- `code --version` und `hx --version` funktionieren.
87+
- `-CompareOnly` meldet keine fehlenden Required-Tools.
88+
- `python3 -m json.tool scripts/config/winget-apps-registry.json` ist erfolgreich.
89+
- `python3 -m json.tool scripts/config/vscode-extensions-registry.json` ist erfolgreich.
90+
- `python3 -m json.tool scripts/config/required-cli-tools-registry.json` ist erfolgreich.
91+
- `python3 -m json.tool scripts/config/npm-agent-cli-registry.json` ist erfolgreich.
92+
- Neue bewusst installierte WinGet-Top-Level-Tools werden in der Registry
93+
nachgetragen.
94+
95+
*`gitleaks version`, `syft version`, `specify --version`, `codex --version`,
96+
`claude --version`, `agy --version`, `copilot --help`, .NET, Go,
97+
Java/Javac, Python, Rust/Cargo, Swift, `code --version`, and `hx --version`
98+
work; `-CompareOnly` reports no missing required tools; the registries are valid
99+
JSON; and intentional new WinGet top-level tools are added to the registry.*
100+
101+
## Sicherheit / Security
102+
103+
Die Registry enthaelt nur Paket-IDs und Zwecke, keine Secrets, lokalen Tokens
104+
oder privaten Pfade. WinGet-Laeufe schreiben ausserhalb des Repositories und
105+
sollen vorab mit `-WhatIf` geprueft werden.
106+
107+
*The registry contains only package IDs and purposes, not secrets, local tokens,
108+
or private paths. WinGet runs write outside the repository and should be
109+
previewed with `-WhatIf` first.*
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
{
2+
"schemaVersion": 1,
3+
"updated": "2026-07-13",
4+
"description": "Homebrew top-level package registry for agentic development across the Level-0, Level-1, and Level-2 repositories.",
5+
"policy": {
6+
"formulaSource": "brew leaves --installed-on-request",
7+
"caskSource": "brew list --cask",
8+
"dependencyPolicy": "Do not list transitive Homebrew dependencies.",
9+
"defaultInstallScope": "required"
10+
},
11+
"formulae": [
12+
{ "name": "acme", "scope": "optional", "purpose": "Plan 9 toolchain experiments" },
13+
{ "name": "antlr", "scope": "optional", "purpose": "Parser and language tooling" },
14+
{ "name": "cc65", "scope": "optional", "purpose": "C64 and 6502 development" },
15+
{ "name": "cmake", "scope": "required", "apt": "cmake", "purpose": "Native build orchestration" },
16+
{ "name": "cmake-docs", "scope": "optional", "purpose": "CMake documentation" },
17+
{ "name": "dotnet", "scope": "required", "purpose": "Memory-safe C#/.NET SDK toolchain" },
18+
{ "name": "gh", "scope": "required", "purpose": "GitHub CLI binary; provider sign-in is required only for the direct GitHub profile" },
19+
{ "name": "gitleaks", "scope": "required", "purpose": "Secret scanning for hooks and manual scans" },
20+
{ "name": "glab", "scope": "required", "purpose": "GitLab CLI binary; provider sign-in is required only for a GitLab profile" },
21+
{ "name": "go", "scope": "required", "purpose": "Memory-safe Go toolchain" },
22+
{ "name": "helix", "scope": "required", "apt": "helix", "purpose": "Terminal-native A11Y editor with language-server support" },
23+
{ "name": "lynx", "scope": "optional", "apt": "lynx", "purpose": "Text browser for accessibility-oriented checks" },
24+
{ "name": "midnight-commander", "scope": "optional", "apt": "mc", "purpose": "Terminal file manager" },
25+
{ "name": "mongodb/brew/mongodb-community", "scope": "optional", "purpose": "MongoDB local database for compatible projects" },
26+
{ "name": "msedit", "scope": "optional", "purpose": "Terminal editor" },
27+
{ "name": "node", "scope": "required", "apt": "nodejs", "purpose": "Node.js and npm runtime for npm-based agent CLI packages" },
28+
{ "name": "oh-my-posh", "scope": "optional", "purpose": "Shell prompt consistency" },
29+
{ "name": "openjdk", "scope": "required", "apt": "default-jdk", "purpose": "Java/Javac MSL toolchain for learning-series repositories" },
30+
{ "name": "opencode", "scope": "required", "purpose": "OpenCode command-line agent" },
31+
{ "name": "pandoc", "scope": "required", "apt": "pandoc", "purpose": "Documentation conversion" },
32+
{ "name": "pnpm", "scope": "required", "purpose": "Node package management for agent/tooling packages" },
33+
{ "name": "podman", "scope": "required", "apt": "podman", "purpose": "Podman CLI for the required Secure Trader sandbox runtime" },
34+
{ "name": "podman-compose", "scope": "required", "apt": "podman-compose", "purpose": "Container compose support for sandbox workflows" },
35+
{ "name": "postgresql@18", "scope": "optional", "purpose": "PostgreSQL local database for compatible projects" },
36+
{ "name": "powershell", "scope": "required", "purpose": "PowerShell 7 parity scripts" },
37+
{ "name": "python@3.14", "scope": "required", "apt": "python3", "purpose": "Python MSL CLI toolchain for learning-series repositories" },
38+
{ "name": "rust", "scope": "required", "purpose": "Memory-safe Rust toolchain" },
39+
{ "name": "syft", "scope": "required", "purpose": "SBOM generation for supply-chain evidence" },
40+
{ "name": "uv", "scope": "required", "purpose": "Python package/tool runner and Spec Kit installation support" },
41+
{ "name": "vice", "scope": "optional", "purpose": "C64 emulator for retro projects" }
42+
],
43+
"casks": [
44+
{ "name": "antigravity-cli", "scope": "required", "purpose": "Google Antigravity command-line agent; maintained Homebrew replacement for the deprecated Gemini CLI formula" },
45+
{ "name": "claude-code", "scope": "required", "purpose": "Claude Code command-line agent" },
46+
{ "name": "copilot-cli", "scope": "required", "purpose": "GitHub Copilot CLI" },
47+
{ "name": "ollama-app", "scope": "optional", "purpose": "Local model runtime app" },
48+
{ "name": "pgadmin4", "scope": "optional", "purpose": "PostgreSQL GUI administration" },
49+
{ "name": "podman-desktop", "scope": "optional", "purpose": "Podman GUI and machine management" },
50+
{ "name": "powershell", "scope": "optional", "purpose": "PowerShell app bundle; formula remains the scripted baseline" },
51+
{ "name": "visual-studio-code", "scope": "required", "purpose": "Minimum graphical editor and quasi-IDE for apprentice development" }
52+
],
53+
"aptFallback": {
54+
"description": "Linux fallback packages for machines without Homebrew. Only explicit mappings are installed.",
55+
"packages": [
56+
{ "name": "git", "scope": "required", "purpose": "Source control" },
57+
{ "name": "ripgrep", "scope": "required", "purpose": "Fast repository search" },
58+
{ "name": "python3", "scope": "required", "purpose": "Python runtime for scripts and validation" },
59+
{ "name": "nodejs", "scope": "required", "purpose": "Node.js runtime where distro package is acceptable" },
60+
{ "name": "npm", "scope": "required", "purpose": "npm package manager for npm-based agent CLI packages" },
61+
{ "name": "golang-go", "scope": "required", "purpose": "Go MSL CLI toolchain when available in configured apt sources" },
62+
{ "name": "cmake", "scope": "required", "purpose": "Native build orchestration" },
63+
{ "name": "default-jdk", "scope": "required", "purpose": "Java/Javac MSL toolchain from configured apt sources" },
64+
{ "name": "pandoc", "scope": "required", "purpose": "Documentation conversion" },
65+
{ "name": "podman", "scope": "required", "purpose": "Podman CLI for the required Secure Trader sandbox runtime" },
66+
{ "name": "podman-compose", "scope": "required", "purpose": "Container compose support" },
67+
{ "name": "rustc", "scope": "required", "purpose": "Rust compiler when available in configured apt sources" },
68+
{ "name": "cargo", "scope": "required", "purpose": "Rust package/build tool when available in configured apt sources" },
69+
{ "name": "helix", "scope": "required", "purpose": "Terminal-native A11Y editor when available in the configured apt sources" },
70+
{ "name": "code", "scope": "required", "purpose": "VS Code package when available in the configured apt sources" }
71+
]
72+
}
73+
}

0 commit comments

Comments
 (0)