Fixes CI, gradient

Author: gzigzigzeo

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
         run: brew install shellcheck bats-core
 
       - name: shellcheck
-        run: shellcheck install.sh global/install-global.sh examples/*.sh
+        run: shellcheck install.sh global/install-global.sh lib/examples/*.sh
 
       - name: bats
         run: bats test/

CONTRIBUTING.md

@@ -27,18 +27,11 @@ never exercises the gradient/color code paths):
 mkdir -p /tmp/run-smoke && cd /tmp/run-smoke
 bash /path/to/run-sh/install.sh --examples
 ./run
-./run new hello
 ./run hello
-./run help hello
 ```
 
 ## Design notes
 
-- `install.sh` and `global/install-global.sh` are meant to be curl-piped
-  standalone, so all generated file content (the `run` dispatcher,
-  `.runrc`, `colors.sh`, the `run new` boilerplate, the global `run`
-  script) is embedded as heredocs directly in these two files — there is
-  no `templates/` directory to keep in sync.
 - Target bash is 3.2 (stock macOS) — avoid associative arrays, `${var,,}`,
   `mapfile`, and other bash-4+ features.
 - `render_run_file` writes its heredoc straight to a temp file rather than

README.md

@@ -1,3 +1,6 @@
+> [!CAUTION]
+> This is work in progress, use on your own risk.
+
 # run.sh
 
 A Makefile replacement written in pure bash. No DSL, no runtime dependencies,
@@ -6,7 +9,7 @@ no build step — just scripts.
 ## Install
 
 ```sh
-curl -fsSL https://raw.githubusercontent.com/imgproxy/run-sh/main/install.sh | bash -e
+curl -fsSL https://raw.githubusercontent.com/imgproxy/run-sh/refs/heads/main/install.sh | bash -s -- -e
 ```
 
 This sets up, in the current project:
@@ -22,15 +25,13 @@ folder for task files.
 
 ```sh
 ./run              # list available tasks
-./run help <task>  # show a task's usage
 ./run <task> [args...]
-./run new <task>   # scaffold a new task file
 ```
 
 ## Optional: global command
 
 ```sh
-curl -fsSL https://raw.githubusercontent.com/imgproxy/run-sh/main/install.sh | bash -s -- -g
+curl -fsSL https://raw.githubusercontent.com/imgproxy/run-sh/refs/heads/main/install.sh | bash -s -- -e -g
 ```
 
 Installs `run` to `~/.local/bin`, which walks up from your current directory
@@ -58,8 +59,44 @@ main() {
 }
 ```
 
-Scaffold one with `./run new <name>`, or see `examples/` for zero-arg,
-positional-arg, flag-parsing, and task-composition patterns.
+See `examples/` for zero-arg, positional-arg, flag-parsing, and
+task-composition patterns.
+
+## Dependencies
+
+Compose tasks with `depends_on` inside a task's `main()`:
+
+```sh
+main() {
+  depends_on build test
+  echo "deploying..."
+}
+```
+
+`depends_on` runs each named task in order and stops at the first failure.
+
+## External libraries
+
+run.sh itself has no runtime dependencies, but your tasks can use any tool you
+already have installed. Install libraries the same way you normally would
+(Homebrew, apt, npm, pip, etc.) and call them from your task files.
+
+For reusable helpers, source them from `.runrc`:
+
+```sh
+# .runrc
+. "$TASK_ROOT/vendor/some-lib.sh"
+```
+
+Use the built-in `require_tool` helper to fail early with a friendly message
+when a required command is missing:
+
+```sh
+main() {
+  require_tool jq "jq is required (https://jqlang.github.io/jq/)"
+  jq '.version' package.json
+}
+```
 
 ## Philosophy
 

docs/index.html

@@ -20,7 +20,7 @@ <h1>run.sh</h1>
 
   <div class="install">
     <code
-      id="install-cmd">curl -fsSL https://raw.githubusercontent.com/imgproxy/run-sh/main/install.sh | bash -e -g</code>
+      id="install-cmd">curl -fsSL https://raw.githubusercontent.com/imgproxy/run-sh/refs/heads/main/install.sh | bash -s -- -e -g</code>
     <button class="copy-btn" onclick="copyInstall(this)">copy</button>
   </div>
 
@@ -57,9 +57,26 @@ <h2>A task looks like this</h2>
   <section>
     <h2>Usage</h2>
     <pre class="snippet"><code>./run              # list available tasks
-./run help &lt;task&gt;  # show a task's usage
-./run &lt;task&gt; [args...]
-./run new &lt;task&gt;   # scaffold a new task file</code></pre>
+./run &lt;task&gt; [args...]</code></pre>
+  </section>
+
+  <section>
+    <h2>Dependencies</h2>
+    <p>
+      Compose tasks with <code>depends_on</code> inside a task's <code>main()</code>.
+      It runs each named task in order and stops at the first failure.
+    </p>
+    <pre class="snippet"><code>main() {
+  depends_on build test
+  echo "deploying..."
+}</code></pre>
+  </section>
+
+  <section>
+    <p>
+      Want to know more? Check the documentation at:
+      <a href="https://github.com/imgproxy/run-sh">github.com/imgproxy/run-sh</a>
+    </p>
   </section>
 
   <footer>

install.sh

@@ -23,27 +23,35 @@ run_colors_enabled() {
   [ "$n" -ge 8 ] 2>/dev/null
 }
 
-run_gradient_text() {
-  local text="$1"
+run_color_echo() {
+  local color="$1" text="$2"
   if ! run_colors_enabled; then
     printf '%s' "$text"
     return
   fi
   local ncolors
   ncolors="$(tput colors 2>/dev/null || echo 0)"
-  if [ "$ncolors" -lt 256 ]; then
-    printf '%s%s%s' "$(tput bold)" "$text" "$(tput sgr0)"
-    return
+  if [ "$ncolors" -ge 256 ]; then
+    case "$color" in
+      red)     printf '\033[38;5;196m%s' "$text" ;;
+      green)   printf '\033[38;5;34m%s'  "$text" ;;
+      blue)    printf '\033[38;5;21m%s'  "$text" ;;
+      cyan)    printf '\033[38;5;45m%s'  "$text" ;;
+      magenta) printf '\033[38;5;201m%s' "$text" ;;
+      neon)    printf '\033[38;5;82m%s'  "$text" ;;
+      *)       printf '%s' "$text" ;;
+    esac
+  else
+    case "$color" in
+      red)     printf '\033[31m%s'  "$text" ;;
+      green)   printf '\033[32m%s'  "$text" ;;
+      blue)    printf '\033[34m%s'  "$text" ;;
+      cyan)    printf '\033[36m%s'  "$text" ;;
+      magenta) printf '\033[35m%s'  "$text" ;;
+      neon)    printf '\033[1;32m%s' "$text" ;;
+      *)       printf '%s' "$text" ;;
+    esac
   fi
-  local i=0 len=${#text} start=63 end=201
-  local span=$((end - start))
-  while [ "$i" -lt "$len" ]; do
-    local ch="${text:$i:1}"
-    local denom=$((len > 1 ? len - 1 : 1))
-    local color=$((start + (span * i) / denom))
-    printf '\033[38;5;%sm%s' "$color" "$ch"
-    i=$((i + 1))
-  done
   printf '%s' "$(tput sgr0)"
 }
 
@@ -243,7 +251,7 @@ install_local() {
   fi
 
   printf '\n'
-  run_gradient_text "run.sh $RUN_VERSION installed"
+  run_color_echo neon "run.sh $RUN_VERSION installed"
   printf '\n\nNext: ./run\n'
 }
 
@@ -252,8 +260,8 @@ RUN_INSTALL_GLOBAL=0
 
 while [ $# -gt 0 ]; do
   case "$1" in
-    -e) RUN_INSTALL_EXAMPLES=1; shift ;;
-    -g) RUN_INSTALL_GLOBAL=1; shift ;;
+    -e|--examples) RUN_INSTALL_EXAMPLES=1; shift ;;
+    -g|--global)   RUN_INSTALL_GLOBAL=1; shift ;;
     -h|--help)
       cat <<EOF
 Usage: install.sh [-e] [-g]

lib/run.sh

@@ -25,72 +25,30 @@ depends_on() {
 
 cmd_list() {
   printf '\n'
-  run_gradient_text "run.sh" 2>/dev/null || printf 'run.sh'
+  run_color_echo neon "run.sh" 2>/dev/null || printf 'run.sh'
   printf ' — tasks in this project\n\n'
-  local f name
+  local f name has_tasks=0
   for f in "$TASK_DIR"/*.sh; do
     [ -e "$f" ] || continue
+    has_tasks=1
     name="$(basename "$f" .sh)"
     # shellcheck disable=SC1090
     printf '  %-15s %s\n' "$name" "$(. "$f"; description)"
   done
-  printf '\n'
-}
-
-cmd_help() {
-  local task="${1:-}"
-  if [ -z "$task" ] || [ ! -f "$TASK_DIR/$task.sh" ]; then
-    echo "error: unknown task '$task'" >&2
-    cmd_list >&2
-    exit 1
-  fi
-  # shellcheck disable=SC1090
-  . "$TASK_DIR/$task.sh"
-  description
-  echo
-  help
-}
-
-cmd_new() {
-  local name="${1:-}"
-  case "$name" in
-    "") echo "usage: ./run new <task-name>" >&2; return 1 ;;
-    run) echo "error: 'run' is reserved (the dispatcher script)" >&2; return 1 ;;
-    *[!a-zA-Z0-9_-]*) echo "error: task name must be alnum/underscore/hyphen" >&2; return 1 ;;
-  esac
-  local target="$TASK_DIR/$name.sh"
-  if [ -e "$target" ] && [ "${2:-}" != "--force" ]; then
-    echo "error: $target already exists (use --force to overwrite)" >&2
-    return 1
+  if [ "$has_tasks" -eq 0 ]; then
+    printf '  No tasks yet.\n\n'
+    printf '  Create your first task by adding a file at %s/<name>.sh:\n\n' "$(basename "$TASK_DIR")"
+    printf '    #!/usr/bin/env bash\n'
+    printf '    description() { echo "One-line summary"; }\n'
+    printf '    help() { echo "Usage: ./run <name> [args...]"; }\n'
+    printf '    main() { echo "task logic goes here, receives \\"$@\\""; }\n\n'
+    printf '  Or scaffold examples with: bash install.sh --examples\n'
   fi
-  cat > "$target" <<TASK_BOILERPLATE
-#!/usr/bin/env bash
-# Sourced by ./run — do not execute directly.
-
-description() {
-  echo "TODO: one-line description of $name"
-}
-
-help() {
-  cat <<'EOF'
-Usage: ./run $name [args...]
-
-TODO: describe usage.
-EOF
-}
-
-main() {
-  echo "TODO: implement $name"
-}
-TASK_BOILERPLATE
-  run_gradient_text "created" 2>/dev/null || printf 'created'
-  printf ' %s\n' "$target"
+  printf '\n'
 }
 
 case "${1:-}" in
   "") cmd_list ;;
-  help) shift; cmd_help "$@" ;;
-  new)  shift; cmd_new "$@" ;;
   *)
     task="$1"; shift
     if [ ! -f "$TASK_DIR/$task.sh" ]; then

lib/runrc.sh

@@ -12,7 +12,7 @@ require_arg() {
   fi
 }
 
-# --- terminal color/gradient helpers (used by ./run and available to tasks) ---
+# --- terminal color helpers (used by ./run and available to tasks) ---
 
 run_colors_enabled() {
   [ -n "${NO_COLOR:-}" ] && return 1
@@ -22,26 +22,34 @@ run_colors_enabled() {
   [ "$n" -ge 8 ] 2>/dev/null
 }
 
-run_gradient_text() {
-  local text="$1"
+run_color_echo() {
+  local color="$1" text="$2"
   if ! run_colors_enabled; then
     printf '%s' "$text"
     return
   fi
   local ncolors
   ncolors="$(tput colors 2>/dev/null || echo 0)"
-  if [ "$ncolors" -lt 256 ]; then
-    printf '%s%s%s' "$(tput bold)" "$text" "$(tput sgr0)"
-    return
+  if [ "$ncolors" -ge 256 ]; then
+    case "$color" in
+      red)     printf '\033[38;5;196m%s' "$text" ;;
+      green)   printf '\033[38;5;34m%s'  "$text" ;;
+      blue)    printf '\033[38;5;21m%s'  "$text" ;;
+      cyan)    printf '\033[38;5;45m%s'  "$text" ;;
+      magenta) printf '\033[38;5;201m%s' "$text" ;;
+      neon)    printf '\033[38;5;82m%s'  "$text" ;;
+      *)       printf '%s' "$text" ;;
+    esac
+  else
+    case "$color" in
+      red)     printf '\033[31m%s'  "$text" ;;
+      green)   printf '\033[32m%s'  "$text" ;;
+      blue)    printf '\033[34m%s'  "$text" ;;
+      cyan)    printf '\033[36m%s'  "$text" ;;
+      magenta) printf '\033[35m%s'  "$text" ;;
+      neon)    printf '\033[1;32m%s' "$text" ;;
+      *)       printf '%s' "$text" ;;
+    esac
   fi
-  local i=0 len=${#text} start=63 end=201
-  local span=$((end - start))
-  while [ "$i" -lt "$len" ]; do
-    local ch="${text:$i:1}"
-    local denom=$((len > 1 ? len - 1 : 1))
-    local color=$((start + (span * i) / denom))
-    printf '\033[38;5;%sm%s' "$color" "$ch"
-    i=$((i + 1))
-  done
   printf '%s' "$(tput sgr0)"
 }