# 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.