From 28d0252a3527d95d84e9ac15bd95f81be5683697 Mon Sep 17 00:00:00 2001 From: ZippyType Date: Fri, 22 May 2026 06:38:37 +0000 Subject: [PATCH] Add AGENTS.md, shellcheck automation, and version-check.sh - AGENTS.md documents LFS build conventions, environment variables, build discipline, and verified host tool versions - .ona/automations.yaml adds two tasks: installShellcheck (runs on postDevcontainerStart) and lintScripts (manual, runs shellcheck against all .sh files) - version-check.sh verifies required LFS host tool versions Co-authored-by: Ona --- .ona/automations.yaml | 50 ++++++++++++++++++++ AGENTS.md | 107 ++++++++++++++++++++++++++++++++++++++++++ version-check.sh | 9 ++++ 3 files changed, 166 insertions(+) create mode 100644 .ona/automations.yaml create mode 100644 AGENTS.md create mode 100755 version-check.sh diff --git a/.ona/automations.yaml b/.ona/automations.yaml new file mode 100644 index 0000000..e5a6c70 --- /dev/null +++ b/.ona/automations.yaml @@ -0,0 +1,50 @@ +tasks: + installShellcheck: + name: Install shellcheck + description: Ensure shellcheck is available for linting shell scripts. + command: | + if ! command -v shellcheck &>/dev/null; then + sudo apt-get update -qq && sudo apt-get install -y shellcheck + else + echo "shellcheck $(shellcheck --version | grep version:) already installed" + fi + triggeredBy: + - postDevcontainerStart + + lintScripts: + name: Lint shell scripts + description: Run shellcheck against all .sh files in the repo and report issues. + command: | + echo "=== Aaron Linux - Shell Script Lint ===" + echo "" + + SCRIPTS=$(find . -name "*.sh" -not -path "./.git/*" | sort) + TOTAL=0 + FAILED=0 + PASSED=0 + + for f in $SCRIPTS; do + TOTAL=$((TOTAL + 1)) + echo "Checking: $f" + if shellcheck -x "$f"; then + PASSED=$((PASSED + 1)) + else + FAILED=$((FAILED + 1)) + fi + echo "" + done + + echo "=======================================" + echo "Results: $TOTAL scripts checked" + echo " Passed : $PASSED" + echo " Failed : $FAILED" + echo "=======================================" + + if [ "$FAILED" -gt 0 ]; then + echo "Fix the issues above and re-run this task." + exit 1 + fi + triggeredBy: + - manual + dependsOn: + - installShellcheck diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..357e5ac --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,107 @@ +# AGENTS.md + +## Project Overview + +This repository is a Linux From Scratch (LFS) build environment. The goal is to compile a complete Linux system from source, following the [LFS book](https://www.linuxfromscratch.org/lfs/). + +## Environment + +This project runs inside a Gitpod (Ona) dev container based on Ubuntu 24.04. + +### Verified Host Tool Versions + +| Tool | Version | +|----------|----------------------------------| +| bash | 5.2.21(1)-release | +| Binutils | 2.42 | +| bison | 3.8.2 | +| gcc | 13.3.0 | +| g++ | 13.3.0 | +| glibc | 2.39 | +| make | 4.3 | + +Run `bash version-check.sh` at any time to re-verify host tool availability. + +### Installed Tools + +- **opencode** (v1.14.50) — AI coding assistant. Run with `opencode` in any project directory. +- **shellcheck** (v0.9.0) — Shell script static analysis tool. + +## Automations + +Defined in `.ona/automations.yaml`. + +| Task | Trigger | Description | +|------|---------|-------------| +| `installShellcheck` | `postDevcontainerStart` | Installs `shellcheck` if not present | +| `lintScripts` | manual | Runs `shellcheck` against all `.sh` files in the repo | + +### Running the linter + +Via the Ona CLI: + +```bash +gitpod automations task start lintScripts +``` + +Or directly: + +```bash +find . -name "*.sh" -not -path "./.git/*" | sort | xargs shellcheck -x +``` + +The linter checks all shell scripts and reports issues by file. Fix `error` and `warning` level findings before committing. `info` level findings are advisory. + +## Agent Guidelines + +### General Rules + +- Follow the LFS book chapter order. Do not skip steps or reorder package builds unless you have a specific reason documented here. +- All source packages must be downloaded to `$LFS/sources` and verified against their checksums before building. +- All builds happen inside `$LFS/sources/`. Clean up build directories after a successful install. +- Never modify files outside `$LFS` unless explicitly required by the host system setup chapters. + +### Environment Variables + +Before running any LFS build commands, ensure these are set: + +```bash +export LFS=/mnt/lfs +export LFS_TGT=$(uname -m)-lfs-linux-gnu +export PATH=/usr/bin:/bin +``` + +For cross-compilation chapters, prepend the toolchain to PATH: + +```bash +export PATH=$LFS/tools/bin:$PATH +``` + +### Build Discipline + +- Always `cd` into the extracted source directory before configuring or building. +- Use `make -j$(nproc)` for parallel builds unless a package is known to fail with parallel jobs. +- After `make install`, return to `$LFS/sources` and remove the build directory. +- Log build output for any package that fails: `make 2>&1 | tee build.log`. + +### Partition and Filesystem + +- The LFS partition is expected at `$LFS` (`/mnt/lfs`). +- Do not run `mkfs` or `fdisk` commands without explicit user confirmation. + +### Committing Changes + +- Commit scripts, patches, and configuration files — not compiled binaries or source tarballs. +- Keep `.gitignore` updated to exclude `$LFS/sources/*.tar.*` and build artifacts. +- Commit messages should state what LFS chapter/step the change relates to. +- All shell scripts must pass `shellcheck` before committing. + +### Using opencode + +opencode is available for AI-assisted coding tasks: + +```bash +opencode # launch in the current directory +``` + +Use it for writing build scripts, debugging compilation errors, or generating patches. diff --git a/version-check.sh b/version-check.sh new file mode 100755 index 0000000..1954001 --- /dev/null +++ b/version-check.sh @@ -0,0 +1,9 @@ +#!/bin/bash +export LC_ALL=C +bash --version | head -n1 | cut -d" " -f2-4 +echo -n "Binutils: "; ld --version | head -n1 | cut -d" " -f3- +bison --version | head -n1 +gcc --version | head -n1 +g++ --version | head -n1 +ldd --version | head -n1 | cut -d" " -f2- # glibc version +make --version | head -n1