Somhairle Scripts
=================

This directory contains personal command-line tools used on this machine.
Tools are managed by the root shm.rkt source script. Installing all tools
creates executable `shm` and tool entrypoints under `.artifacts/bin/`, then
links those entrypoints into the user's local bin directory.

Current tools
-------------

git-tools
  Provides Git external commands for ergonomic repository inspection:
  git-st, git-dst, git-lg, git-br, and git-stashs. They are intended to be
  called through git aliases such as `git st` and `git lg`.

mysql-tools
  Provides MySQL helper commands for connection checks, table size reports,
  mysql-check and mysql-size.

sync-mysql-db
  Dumps one MySQL database and restores it into another. It supports direct
  MySQL connections, optional SSH tunnels for the source or target database,
  dry-run plan output, connection checks, confirmation prompts, and temporary
  dump cleanup.

system-tools
  Provides local machine inspection helpers: port, ports, svc, net-who,
  path-ls, and cmd-which.

Directory layout
----------------

Each tool has its own directory under tools/ with the implementation and a
dedicated README describing usage and behavior in detail. Installed entrypoints
are lightweight Racket launchers under `.artifacts/bin/` by default, with
matching symlinks in ~/.local/bin for PATH usage. The repository root stays
source-only.

Management
----------

The root shm.rkt script discovers tool directories that provide their own
manage.rkt script. The root script delegates install, uninstall, and status work
to each tool-specific manager.

Common commands:

  racket shm.rkt list
  racket shm.rkt status
  racket shm.rkt status git-tools
  racket shm.rkt status sync-mysql-db
  racket shm.rkt install git-tools
  racket shm.rkt install mysql-tools
  racket shm.rkt install sync-mysql-db
  racket shm.rkt install system-tools
  racket shm.rkt update
  racket shm.rkt update git-tools
  racket shm.rkt doctor
  racket shm.rkt prune --dry-run
  racket shm.rkt prune
  racket shm.rkt uninstall sync-mysql-db
  racket shm.rkt install all
  racket shm.rkt install all --standalone
  racket shm.rkt install all --source
  racket shm.rkt uninstall all

During development, the source scripts can also be run directly:

  ./shm.rkt list
  racket tools/sync-mysql-db/sync-mysql-db.rkt --help

After `racket shm.rkt install all`, the manager can be run from any directory
when ~/.local/bin is on PATH:

  shm status

Launcher, standalone, and source installs
-----------------------------------------

The default install mode builds tiny Racket launchers with `raco exe
--launcher` and links entrypoints to those build outputs. Installed commands do
not have a `.rkt` suffix and are available on PATH when ~/.local/bin is on PATH:

  racket shm.rkt install all

  shm status
  git st
  git lg --no-pager -n 5
  mysql-check --url mysql://user:password@127.0.0.1:3306/database
  mysql-size mysql://user:password@127.0.0.1:3306/database
  mysql-size --url mysql://user:password@127.0.0.1:3306/database
  path-ls
  cmd-which racket
  port 3306
  ports
  svc ssh
  net-who mysql
  sync-mysql-db --help

Compiled outputs are written under:

  .artifacts/bin/

Tool executables stay in the artifact directory, and PATH entrypoints link
directly to those artifact executables:

  .artifacts/bin/sync-mysql-db
  .artifacts/bin/git-st
  .artifacts/bin/git-lg
  ~/.local/bin/sync-mysql-db -> <repo>/.artifacts/bin/sync-mysql-db
  ~/.local/bin/git-st -> <repo>/.artifacts/bin/git-st

Standalone mode is available when commands need to carry an embedded Racket
runtime:

  racket shm.rkt install all --standalone

Source install mode is available for debugging and links entrypoints to source
.rkt scripts:

  racket shm.rkt install all --source

The source scripts remain the canonical implementation. Launcher and standalone
outputs are local build artifacts and are not tracked by git. Re-run the update
command after changing a script.

Maintenance
-----------

The manager includes maintenance commands for keeping the local installation
healthy:

  racket shm.rkt doctor
    Check Racket and raco availability, PATH setup, manager ownership, tool
    entrypoints, and compiled artifact presence.

  racket shm.rkt update
    Rebuild and relink all tools in launcher mode. A specific tool can be
    updated with `racket shm.rkt update git-tools`. Standalone and source modes
    are available with `--standalone` and `--source`.

  racket shm.rkt prune --dry-run
    Preview stale managed artifacts, stale repository executables, and
    broken managed PATH symlinks.

  racket shm.rkt prune
    Remove the stale files shown by the prune scan. Active compiled
    entrypoints that are linked from ~/.local/bin are kept.

Tool manage.rkt contract:

  --metadata
    Print machine-readable JSON with name, description, and entrypoints.

  --status
    Show whether the tool entrypoints are installed.

  --install --repo-root <path>
    Build lightweight launchers and install entrypoints to artifact outputs.

  --install --repo-root <path> --standalone
    Build self-contained executables with embedded Racket runtime.

  --install --repo-root <path> --source
    Link the tool entrypoints to source scripts.

  --uninstall --repo-root <path>
    Remove only the entrypoints owned by the tool.

Requirements
------------

Required runtime:

  - Racket 9.x

Launcher and standalone install requirement:

  - raco exe, included with the standard Racket distribution

Tests
-----

Run the RackUnit test suite with:

  raco test tests/sync-mysql-db-test.rkt
  raco test tests/shm-test.rkt