update

2026-07-25 17:28:23 -05:00
parent b04e5b706d
commit d47a88587c
7 changed files with 211 additions and 45 deletions
@@ -0,0 +1,94 @@
+# iDS-Defaults
+
+iDS-Defaults is a shared Bash library used by other iDS projects. It provides
+terminal color definitions and common helpers for formatting, host checks,
+notifications, operating-system detection, and other administrative scripts.
+
+## Requirements
+
+- Linux
+- Bash 4 or newer
+- Additional commands used by individual helpers include `awk`, `grepcidr`,
+  `ping`, `pgrep`, `ssh`, `systemctl`, and `wget`.
+
+Not every command is required by every consumer. A host only needs the commands
+used by the functions it calls.
+
+## Current installation
+
+The current/default version is installed at:
+
+```text
+/opt/idssys/defaults
+```
+
+Existing projects can continue to source it without specifying a version:
+
+```bash
+source /opt/idssys/defaults/colors.inc
+source /opt/idssys/defaults/default.inc
+```
+
+The `master` branch is the current/default release channel. The installed
+version can be read from `/opt/idssys/defaults/VERSION`.
+
+## Pinned versions
+
+Projects that require a specific release can install its Git tag in a separate
+directory:
+
+```text
+/opt/idssys/defaults-versions/v1.0.0
+```
+
+That project then sources the pinned copy:
+
+```bash
+source /opt/idssys/defaults-versions/v1.0.0/colors.inc
+source /opt/idssys/defaults-versions/v1.0.0/default.inc
+```
+
+Multiple tagged versions may coexist on one host. Pinned versions should be
+installed only when needed; a project must not change the shared current
+checkout to satisfy its own version requirement.
+
+Release tags use the `vMAJOR.MINOR.PATCH` form. The `VERSION` file omits the
+leading `v`.
+
+## List terminal colors remotely
+
+`list-colors.sh` is self-contained when iDS-Defaults is not installed:
+
+```bash
+curl --fail --show-error --location \
+  https://git.schroedercity.com/voltron/iDS-Defaults/raw/master/list-colors.sh |
+  bash
+```
+
+When `/opt/idssys/defaults` is present, the script uses the installed
+`colors.inc`. Otherwise, it uses its embedded color definitions and performs no
+secondary download.
+
+## Compatibility
+
+The include files are shared APIs. Existing function names and behavior should
+remain compatible unless a change is explicitly reviewed. New or incompatible
+behavior should normally be introduced under a new function name or in a new
+major release.
+
+Sourcing `default.inc` defines functions and global variables in the calling
+shell. Some legacy helpers also inspect the host environment when sourced.
+
+## Maintenance checks
+
+Run the optional local smoke test with:
+
+```bash
+./tests/smoke-test.sh
+```
+
+The test performs syntax and local value checks only. It is never run when a
+consumer sources iDS-Defaults and adds no runtime overhead to other projects.
+
+`test.sh` is intentionally retained as a small scratch script for remote
+testing.