Apps: install, update & scan

lib/apps/ - the machinery behind the dabt command: installing and running DABT applications (dabt app), installing and updating DABT itself (install.sh, dabt update), the three-way file sync both use, and the security scanner (dabt scan). Guide: ../guide/install-and-update.md. ← API index for the full module list and a task-oriented tour with examples.

Apps rarely call these directly. tui_sync.sh, tui_install.sh and tui_update.sh are loaded by tui.sh; tui_apps.sh is loaded by bin/dabt only, and tui_scan.sh on demand (tui.require tui_scan). None of them needs a running TUI except the functions marked “inside the app”. Functions return 0 unless their entry says otherwise.

Applications

An application is a folder with a .dabt.metadata file (name, entry, and optionally version, title, description, author, own_dir, install_hook, uninstall_hook, min_dabt, max_dabt).

Function	Summary
`tui.apps.install`	Installs a DABT application from a folder or a git URL (`URL#ref` for a branch or tag). `dabt app install` calls it.
`tui.apps.update`	Reinstalls apps from their recorded source (all when no `NAME` is given), keeping each app’s settings files.
`tui.apps.remove`	Uninstalls an app after running its `uninstall_hook`. Its settings folder is kept unless `--purge` is given; `--yes` skips the confirmation.
`tui.apps.list`	Prints a table of installed apps: name, version, entry and location.
`tui.apps.info`	Prints the details of an installed app, including its metadata. Returns `1` when it is not installed.
`tui.apps.run`	Starts an installed app by name, or an app folder or script directly, passing `ARGS` on. `dabt app run` calls it.
`tui.apps.meta_load`	Parses and validates `DIR/.dabt.metadata` into the associative array `TUI_APP_META`. Returns `1` with the reason in `TUI_APPS_ERROR`.
`tui.apps.compat`	Checks the loaded `TUI_APP_META` against this DABT version (`min_dabt`, `max_dabt`, both inclusive). Returns `1` with the reason in `TUI_APPS_ERROR`.
`tui.apps.cli`	The `dabt app` command line: `install`, `update`, `remove`, `list`, `info`, `run`, `help`.

`tui.apps.install`

tui.apps.install SRC [--force] [--name NAME] [--entry REL]

Installs a DABT application from a folder or a git URL (URL#ref for a branch or tag). dabt app install calls it.

Options

--force: install a folder without a .dabt.metadata file (then --name and --entry are needed), or replace an installed app.
--name NAME, --entry REL: override or supply the name and the start script.

Notes

The app’s .dabt.metadata must name name and entry; min_dabt/max_dabt are checked against this version.
The app goes to ~/.config/DABT/apps/NAME, or ~/.local/share/dabt-apps/NAME with own_dir=yes, and is recorded in $TUI_HOME/apps.list.
Runs the app’s install_hook, if any. A failing hook only warns.

`tui.apps.update`

tui.apps.update [NAME...]

Reinstalls apps from their recorded source (all when no NAME is given), keeping each app’s settings files.

`tui.apps.remove`

tui.apps.remove NAME [--yes] [--purge]

Uninstalls an app after running its uninstall_hook. Its settings folder is kept unless --purge is given; --yes skips the confirmation.

`tui.apps.list`

tui.apps.list

Prints a table of installed apps: name, version, entry and location.

`tui.apps.info`

tui.apps.info NAME

Prints the details of an installed app, including its metadata. Returns 1 when it is not installed.

`tui.apps.run`

tui.apps.run [--entry PATH] [--force] NAME|PATH|DIR [ARGS...]

Starts an installed app by name, or an app folder or script directly, passing ARGS on. dabt app run calls it.

Notes

Returns 2 for an unknown option.

`tui.apps.meta_load`

tui.apps.meta_load DIR

Parses and validates DIR/.dabt.metadata into the associative array TUI_APP_META. Returns 1 with the reason in TUI_APPS_ERROR.

`tui.apps.compat`

tui.apps.compat

Checks the loaded TUI_APP_META against this DABT version (min_dabt, max_dabt, both inclusive). Returns 1 with the reason in TUI_APPS_ERROR.

`tui.apps.cli`

tui.apps.cli ARGS...

The dabt app command line: install, update, remove, list, info, run, help.

Installing DABT

Function	Summary
`tui.install.defaults`	Sets the default install locations: `TUI_INSTALL_PREFIX` (`~/.local/share/dabt`), `TUI_INSTALL_CONFIG` (`~/.config/DABT`), `TUI_INSTALL_BINDIR` (`~/.local/bin`). XDG variables are respected.
`tui.install.detect`	Prints an existing DABT config home: `~/.config/DABT` if it exists, else `$DABT_HOME` if it is a folder. Returns `1` when there is none.
`tui.install.check_dir`	Returns `0` when `DIR` is absolute and is a writable folder or can be created. Otherwise returns `1` with the reason in `TUI_INSTALL_ERROR`.
`tui.install.run`	Installs DABT from a release folder: copies the program to `PREFIX`, the defaults and plugins into `CONFIG`, and links `dabt` into the bin folder. `install.sh` calls it.

`tui.install.defaults`

tui.install.defaults

Sets the default install locations: TUI_INSTALL_PREFIX (~/.local/share/dabt), TUI_INSTALL_CONFIG (~/.config/DABT), TUI_INSTALL_BINDIR (~/.local/bin). XDG variables are respected.

`tui.install.detect`

tui.install.detect

Prints an existing DABT config home: ~/.config/DABT if it exists, else $DABT_HOME if it is a folder. Returns 1 when there is none.

`tui.install.check_dir`

tui.install.check_dir DIR

Returns 0 when DIR is absolute and is a writable folder or can be created. Otherwise returns 1 with the reason in TUI_INSTALL_ERROR.

`tui.install.run`

tui.install.run SRC PREFIX CONFIG [--policy override|skip|new] [--bindir DIR | --no-link] [--dry-run] [--resolver FN]

Installs DABT from a release folder: copies the program to PREFIX, the defaults and plugins into CONFIG, and links dabt into the bin folder. install.sh calls it.

Returns: 0 done, 1 failed, 2 SRC is not a valid release.

Sets: TUI_INSTALL_LOG (lines), and the plan arrays of tui.sync.plan.

Notes

Config files you changed are handled by the conflict policy; see tui.sync.apply.
When CONFIG is not the default, PREFIX/etc/dabt.env records it so the program can find it.

File sync

Program files (lib/ bin/ share/ docs/ examples/ VERSION ...) are always replaced by the release. Config files (share/defaults/** → CONFIG/defaults/, share/plugins/* → CONFIG/plugins/) are compared three ways: the checksum DABT recorded when it last wrote the file, the file now, and the release. Files you changed are never overwritten silently.

Function	Summary
`tui.sync.plan`	Compares the config files of a release (`share/defaults/*`, `share/plugins/`) with the installed ones, using the checksums in `CONFIG/manifest` as the common base.
`tui.sync.apply`	Applies the plan from `tui.sync.plan` and rewrites `CONFIG/manifest`.
`tui.sync.program_plan`	Compares the program files of a release with `PREFIX`. Sets `TUI_SYNC_P_ADD`, `TUI_SYNC_P_UPDATE`, `TUI_SYNC_P_SAME`, `TUI_SYNC_P_REMOVE`.
`tui.sync.program_apply`	Applies the program plan: program files are always replaced by the release’s, with the old ones copied to `BACKUP_DIR`.
`tui.sync.valid_source`	Returns `0` when `SRC` looks like a DABT release (`VERSION`, `lib/tui.sh`, `share/defaults`).
`tui.sync.report`	Prints the last plans as a readable list: files added, changed, removed and in conflict.
`tui.sync.resolve_ui`	Inside the app: asks about each conflict of the current plan in a dialog (override, skip, `.new`, show the differences, same for the rest), then calls `DONE_FN`.

`tui.sync.plan`

tui.sync.plan SRC CONFIG

Compares the config files of a release (share/defaults/**, share/plugins/*) with the installed ones, using the checksums in CONFIG/manifest as the common base.

Sets: arrays of CONFIG-relative paths: TUI_SYNC_ADD (new), TUI_SYNC_UPDATE (you hadn’t changed it), TUI_SYNC_SAME, TUI_SYNC_KEEP (only you changed it), TUI_SYNC_CONFLICT (both changed), TUI_SYNC_REMOVE (dropped, untouched), TUI_SYNC_ORPHAN (dropped, but you changed it).

`tui.sync.apply`

tui.sync.apply SRC CONFIG [RESOLVER]

Applies the plan from tui.sync.plan and rewrites CONFIG/manifest.

Parameters

RESOLVER: function called as RESOLVER REL for each conflict; prints override (take the release’s file), skip (keep yours) or new (write the release’s as FILE.new). Without it, TUI_SYNC_POLICY decides (default new).

Sets: TUI_SYNC_BACKUP (the backup folder), TUI_SYNC_COUNT (counts per action).

Notes

Every file it replaces is copied to CONFIG/backups/STAMP/ first.

`tui.sync.program_plan`

tui.sync.program_plan SRC PREFIX

Compares the program files of a release with PREFIX. Sets TUI_SYNC_P_ADD, TUI_SYNC_P_UPDATE, TUI_SYNC_P_SAME, TUI_SYNC_P_REMOVE.

`tui.sync.program_apply`

tui.sync.program_apply SRC PREFIX [BACKUP_DIR]

Applies the program plan: program files are always replaced by the release’s, with the old ones copied to BACKUP_DIR.

`tui.sync.valid_source`

tui.sync.valid_source SRC

Returns 0 when SRC looks like a DABT release (VERSION, lib/tui.sh, share/defaults).

`tui.sync.report`

tui.sync.report

Prints the last plans as a readable list: files added, changed, removed and in conflict.

`tui.sync.resolve_ui`

tui.sync.resolve_ui DONE_FN [SRC]

Inside the app: asks about each conflict of the current plan in a dialog (override, skip, .new, show the differences, same for the rest), then calls DONE_FN.

Notes

The answers are in TUI_SYNC_DECISION; apply them with tui.sync.apply SRC CONFIG _tui_sync.decided.

Updating DABT

Function	Summary
`tui.update.check`	Asks GitHub for the latest DABT version.
`tui.update.download`	Downloads and unpacks the latest release into `DIR/src`. Returns `1` with the reason in `TUI_UPDATE_ERROR`.
`tui.update.local`	Prepares a local update source in `DIR/src` from a release folder, a `.tar.gz`, or a `.dapk` package (verified first). Sets `TUI_UPDATE_SRC_KIND` (`folder`, `archive`, `dapk`).
`tui.update.plan`	Compares `SRC` with the installed DABT and fills the plan arrays of `tui.sync.*`. Sets `TUI_UPDATE_GIT=1` when the installed program is a git checkout.
`tui.update.apply`	Applies an update: program files (skipped for a git checkout), config files with conflict handling, and `install.meta`. Sets `TUI_UPDATE_RESULT` (lines).
`tui.update.cli`	The `dabt update` command line, without a TUI.
`tui.version.newer`	Returns `0` when version `A` is newer than `B`, comparing dotted numbers (`0.10.0` is newer than `0.9.2`).
`tui.action.update_check`	Inside the app: checks for an update and offers to download it, or shows a toast that DABT is up to date. In the palette as “DABT: Check for updates”.
`tui.action.update`	Inside the app: downloads the latest release, shows what would change, asks about conflicts, then applies the update. Returns `1` when the download fails.

`tui.update.check`

tui.update.check

Asks GitHub for the latest DABT version.

Returns: 0 a newer version is available, 1 up to date, 2 the check failed (reason in TUI_UPDATE_ERROR).

Sets: TUI_UPDATE_LATEST.

Notes

Channel release (default) uses the latest GitHub release; TUI_UPDATE_CHANNEL=dev uses the current main and always offers it.
Needs curl or wget. TUI_UPDATE_REPO, TUI_UPDATE_BRANCH, TUI_UPDATE_VERSION_URL and TUI_UPDATE_ARCHIVE_URL override the source.

`tui.update.download`

tui.update.download DIR

Downloads and unpacks the latest release into DIR/src. Returns 1 with the reason in TUI_UPDATE_ERROR.

Notes

Needs tar and curl or wget.

`tui.update.local`

tui.update.local PATH DIR

Prepares a local update source in DIR/src from a release folder, a .tar.gz, or a .dapk package (verified first). Sets TUI_UPDATE_SRC_KIND (folder, archive, dapk).

Notes

For a .dapk, TUI_UPDATE_LOCAL_WORK names a work folder to delete afterwards.

`tui.update.plan`

tui.update.plan SRC

Compares SRC with the installed DABT and fills the plan arrays of tui.sync.*. Sets TUI_UPDATE_GIT=1 when the installed program is a git checkout.

`tui.update.apply`

tui.update.apply SRC [RESOLVER]

Applies an update: program files (skipped for a git checkout), config files with conflict handling, and install.meta. Sets TUI_UPDATE_RESULT (lines).

`tui.update.cli`

tui.update.cli [--check] [--yes] [--dev|--release] [--path PATH [--trust-key KEY] [--allow-unsigned]] [--policy override|skip|new] [--force] [--no-scan]

The dabt update command line, without a TUI.

`tui.version.newer`

tui.version.newer A B

Returns 0 when version A is newer than B, comparing dotted numbers (0.10.0 is newer than 0.9.2).

`tui.action.update_check`

tui.action.update_check

Inside the app: checks for an update and offers to download it, or shows a toast that DABT is up to date. In the palette as “DABT: Check for updates”.

`tui.action.update`

tui.action.update

Inside the app: downloads the latest release, shows what would change, asks about conflicts, then applies the update. Returns 1 when the download fails.

Security scan

Function	Summary
`tui.scan.run`	Security-scans a script or folder for obvious red flags: pipe-to-shell, reverse shells, `rm -rf /`, setuid, secrets, persistence.
`tui.scan.run_spin`	Runs `tui.scan.run` behind a spinner (a plain message when stdout is not a terminal). Sets the same variables.
`tui.scan.print`	Prints `TUI_SCAN_REPORT` and a summary line.
`tui.scan.tools`	Prints whether ShellCheck and Semgrep are installed, and which package manager was found.
`tui.scan.install`	Installs an optional scanner with the system package manager.
`tui.scan.cli`	The `dabt scan` command line: `PATH... [--deep] [--strict]`, `--tools`, `--install TOOL`.

`tui.scan.run`

tui.scan.run PATH [DEEP]

Security-scans a script or folder for obvious red flags: pipe-to-shell, reverse shells, rm -rf /, setuid, secrets, persistence.

Parameters

DEEP: 1 also runs Semgrep when installed (or set DABT_SCAN_SEMGREP=1). ShellCheck runs whenever it is on PATH.

Sets: TUI_SCAN_HIGH, TUI_SCAN_WARN (counts), TUI_SCAN_REPORT (text).

Returns: always 0; check the counts.

Notes

Static checks only: obfuscated code is not detected, so a clean report is not a guarantee.
Not loaded by tui.sh; call tui.require tui_scan first.

`tui.scan.run_spin`

tui.scan.run_spin PATH [MSG] [DEEP]

Runs tui.scan.run behind a spinner (a plain message when stdout is not a terminal). Sets the same variables.

`tui.scan.print`

tui.scan.print

Prints TUI_SCAN_REPORT and a summary line.

`tui.scan.tools`

tui.scan.tools

Prints whether ShellCheck and Semgrep are installed, and which package manager was found.

`tui.scan.install`

tui.scan.install shellcheck|semgrep [--yes]

Installs an optional scanner with the system package manager.

`tui.scan.cli`

tui.scan.cli ARGS...

The dabt scan command line: PATH... [--deep] [--strict], --tools, --install TOOL.