@gspothq/cli 0.0.0-stage → 0.1.0

package/configurations/language/bash/rules/LANGUAGE.md

@@ -0,0 +1,213 @@
+# Bash Language
+
+## Functions
+
+Declare function-local variables with `local`, and separate the declaration from a command
+substitution assignment when the exit code matters, because `local`, `declare`, `readonly`,
+and `export` report their own status rather than the substitution's:
+
+```bash
+local output
+output="$(some_command)" || return 1
+```
+
+Preserve the documented status contract: a predicate may use status 1 for false, kept
+distinct from an execution error. At level `all`, every executable defines `main` and calls it last.
+
+```bash
+# report_unreadable_files: Reports each unreadable input and fails if any input is unreadable.
+report_unreadable_files() {
+  local path
+  local status=0
+
+  for path in "$@"; do
+    if [[ -r ${path} ]]; then
+      continue
+    fi
+    printf 'error: input is unreadable: %s\n' "${path}" >&2
+    status=1
+  done
+  return "${status}"
+}
+```
+
+### Function conventions
+
+<!-- level: all -->
+
+Use `name() { ... }` for a function that runs in the caller's shell, and a subshell body,
+`name() ( ... )`, for deliberate isolation of the caller's state and traps.
+
+## Variables and constants
+
+Mark constants `readonly` immediately after assignment, and
+`export` only what child processes need. Never casually overwrite `PATH`, `HOME`, `IFS`,
+`CDPATH`, `SHELL`, `PWD`, or `BASH_ENV`, and never export `CDPATH`.
+
+Compute a directory constant with `CDPATH='' cd -- <path> && pwd -P` and carries a failure path, `|| exit 1` in an
+entrypoint and `|| return 1` in a library. Use `$HOME`, not a quoted `~`, inside paths, and
+assign a home-relative value before exporting it. Quote array elements passed to `unset -v`.
+
+```bash
+script_parent="$(dirname -- "${BASH_SOURCE[0]}")" || exit 1
+PROJECT_ROOT="$(CDPATH='' cd -- "${script_parent}/.." && pwd -P)" || exit 1
+readonly PROJECT_ROOT
+export PROJECT_ROOT
+```
+
+## Quoting and expansion
+
+Forward arguments with `"$@"`, and use `$*` only to join arguments into one string on
+purpose. Single quotes hold literals and double quotes hold expansions. Command substitution
+output never supplies an unquoted argument list, and word splitting never parses data. Use functions,
+not aliases. Parameter expansion replaces external tools for string work:
+
+```bash
+filename="archive.tar.gz"
+base="${filename%.tar.gz}"
+```
+
+## Arrays and argument lists
+
+Command arguments live in arrays, expanded with `"${array[@]}"` and never populated from raw
+`$(...)`. Read lines with a `while read` loop or `readarray`, and read filenames from `NUL`-delimited streams:
+
+```bash
+declare -a archive_args
+archive_args=(-czf "${archive_path}" -C "${source_directory}" .)
+tar "${archive_args[@]}"
+
+while IFS= LC_ALL=C read -r -d '' file; do
+  files+=("${file}")
+done < <(find . -type f -name '*.sql' -print0)
+```
+
+Do not use arrays to imitate nested data structures. A need for those structures signals that the work belongs outside Bash.
+
+## Conditionals and arithmetic
+
+`[[ ... ]]` holds string, pattern, and file tests. `==` compares for equality with a quoted
+right-hand side when the value may hold glob characters, and an unquoted right-hand side only
+for pattern matching. Store a regular expression in a variable and use it
+unquoted with `=~`. `-z` and `-n` test for emptiness. Numeric comparisons live in `(( ... ))` after validation of untrusted numbers; `<` and
+`>` inside `[[ ... ]]` compare strings.
+
+```bash
+readonly version_re='^[0-9]+\.[0-9]+\.[0-9]+$'
+if [[ "${version}" =~ ${version_re} ]]; then
+  printf 'valid version\n'
+fi
+```
+
+Arithmetic uses `$(( ... ))` and `(( ... ))`. `(( i++ ))` returns false when the expression equals
+zero, so under `errexit` increment with `retry_count=$(( retry_count + 1 ))`. Untrusted
+strings never enter `(( ... ))`, `$(( ... ))`, `[[ value -gt n ]]`, array indices, or
+arithmetic `for` expressions: validate with a pattern first. `10#${value}` converts unsigned
+base-10 strings; a signed value needs `$(( ${value%%[!+-]*}10#${value#[-+]} ))`. Call `date`
+once when several fields describe one instant, and compute a redirection path before the
+command when the path expression mutates a variable.
+
+```bash
+if [[ ! "${port}" =~ ^[0-9]{1,5}$ ]]; then
+  printf 'error: port must be numeric\n' >&2
+  return 1
+fi
+if (( 10#${port} < 1 || 10#${port} > 65535 )); then
+  printf 'error: port is out of range\n' >&2
+  return 1
+fi
+```
+
+## Loops and delimited data
+
+Iterate arguments with `for arg in "$@"; do`, globs directly rather than `ls`, and files with
+`while IFS= read -r line || [[ -n ${line} ]]; do ... done <"${file}"`, which keeps the last
+unterminated line. A pipe into `while` runs the loop in a subshell, so variables set inside it
+vanish; use process substitution or a redirected file. A here-string with command
+substitution collects all output first, strips trailing newlines, and drops `NUL` bytes.
+Neither form propagates the producer's failure; use a checked temporary file when that status
+matters. Counter loops use `for (( index = 0; index < count; index++ ))`, not `seq`.
+
+```bash
+root_dir="$(CDPATH='' cd -- "${1:?Root directory is required}" && pwd -P)" || exit 1
+file_list="$(mktemp)" || exit 1
+trap 'rm -f -- "${file_list}"' EXIT
+find "${root_dir}" -type f -print0 >"${file_list}" || exit 1
+
+while IFS= LC_ALL=C read -r -d '' file; do
+  printf 'file: %q\n' "${file}"
+done <"${file_list}"
+```
+
+`IFS= read -r` prevents trimming and backslash handling. Do not save and restore `IFS` with
+`old_ifs="${IFS}"`, which loses the distinction between unset and empty; use a function-local
+`IFS` or a subshell. `read` treats `IFS` as a terminator, so a controlled delimited line
+keeps its trailing empty field only with an appended delimiter. Parse general CSV with
+application code with a real parser, never `IFS=, read`.
+
+```bash
+# join_path_parts: Joins the arguments with slashes.
+join_path_parts() {
+  local IFS='/'
+  printf '%s\n' "$*"
+}
+```
+
+## Paths, globs, and file names
+
+Quote paths, put `--` before path arguments where the command supports it, prefer globs with
+an explicit prefix such as `./*.sql`, and never filter filenames with `grep`. Filenames can
+hold spaces, newlines, quotes, brackets, and leading dashes. Never assume the current
+directory; compute it, and check `cd` explicitly. A broken symlink needs `-L` beside `-e`
+when existence matters, and a basename pattern reads `"${path##*/}"`. Handle the no-match
+glob deliberately, either with `[[ -e ${file} ]] || continue` or with `nullglob` scoped to a
+subshell:
+
+```bash
+for file in ./*.sql; do
+  [[ -e ${file} ]] || continue
+  printf '%s\n' "${file}"
+done
+
+if ! cd -- "${target_dir}"; then
+  printf 'error: cannot enter target dir: %s\n' "${target_dir}" >&2
+  return 1
+fi
+```
+
+## Command substitution
+
+Quote `$(...)`, capture the status at once, and remember that it strips trailing newlines,
+cannot carry binary data, and never builds an argument list. Use `$(<file)` only when
+the operation allows stripping trailing newlines. When trailing newlines matter, keep them with a
+sentinel:
+
+```bash
+commit_sha="$(git rev-parse HEAD)" || exit 1
+content_with_sentinel="$(some_command || exit; printf x)" || return 1
+content="${content_with_sentinel%x}"
+```
+
+## Pipelines and redirection
+
+Read `PIPESTATUS` immediately when individual statuses matter. Order redirections to show the intent, `>file 2>&1`, and never close a standard descriptor as a shortcut for `/dev/null`. A
+pipeline never reads from and writes to the same file; rewrite a file through a
+temporary file and an atomic rename. Parallel `xargs` jobs do not produce ordered, unmixed
+output: write per-job files and combine them, or use a tool that serializes. Check a command
+directly or capture its status in a named variable rather than `(( ! $? )) || die`.
+
+```bash
+tar -cf - ./* | (cd -- "${target_dir}" && tar -xf -)
+statuses=( "${PIPESTATUS[@]}" )
+if (( statuses[0] != 0 || statuses[1] != 0 )); then
+  printf 'error: tar copy failed\n' >&2
+  return 1
+fi
+
+edited_file="$(mktemp "${file}.XXXXXX")" || return 1
+sed 's/foo/bar/g' "${file}" >"${edited_file}" || {
+  rm -f -- "${edited_file}"
+  return 1
+}
+mv -- "${edited_file}" "${file}"
+```

package/configurations/language/bash/rules/NAMING.md

@@ -0,0 +1,62 @@
+# Bash Naming
+
+Bash naming follows Google shell guidance, with the overrides below for file stems.
+
+## Bash case rules
+
+<!-- level: all -->
+
+- Executable scripts use `.sh` when invoked through a task runner or build
+  rules.
+- Omit the extension on an executable script only when users invoke it
+  as a command on `PATH`.
+- Give sourced libraries the `.sh` extension and no executable permission.
+- Numbered pipeline steps use `NN-description.sh`, such as `01-install.sh`; the numeric prefix defines a
+  structural prefix the naming check strips before it matches the stem.
+- Functions and mutable variables use `lower_snake_case`.
+- Package-like function prefixes may use `::` only when a script family already
+  uses that convention.
+
+| Avoid              | Prefer                     | Meaning              |
+| ------------------ | -------------------------- | -------------------- |
+| `DeployScript.sh`  | `deploy-api.sh`            | API deployment.      |
+| `deploy_script.sh` | `upload-storage-assets.sh` | Storage upload.      |
+| `helpers.sh`       | `archive-reports`          | A command on `PATH`. |
+
+Name a deployment function `deploy_api` and its local target
+`target_environment`.
+
+## Bash variables
+
+<!-- level: all -->
+
+- Loop variables name each item in the loop.
+- Name a temporary path after what it holds, such as `download_file` or `work_dir`; `tmp` and
+  `temp` say nothing.
+- Avoid vague names when the domain provides a name.
+- Avoid shell-reserved and shell-special names for unrelated values.
+
+Use `migration_file` when iterating migration paths and `report_output` for
+captured report text. Check the report command's exit status before printing
+the captured output. A loop variable such as `i` does not describe a file.
+
+## Bash functions
+
+<!-- level: all -->
+
+- Function names use verb phrases when the function has side effects.
+- Name a function that prints to `stdout` for the data it prints.
+- Do not name scripts or functions after shell builtins or common commands.
+- Do not make function names so generic that logs and stack traces lose context.
+
+Name a port validator `validate_port`. Avoid `test`, which shadows a shell builtin, and
+generic names such as `run` or `process`.
+
+## Files
+
+<!-- level: all -->
+
+- Put a related script family in an owning subdirectory and give the contained
+  files role names such as `main.sh`, `state.sh`, `query.sh`, or `report.sh`.
+- External hook families may use a dynamic shared prefix when the external
+  interface owns those filenames.

package/configurations/language/bash/rules/OPERATIONS.md

@@ -0,0 +1,77 @@
+# Bash Operations
+
+## Module ownership and visibility
+
+<!-- level: all -->
+
+Each file owns one cohesive responsibility, and the directory supplies the family name.
+
+- A sourced public function carries its family name, such as `release_prepare` or
+  `cache_read_state`.
+- A function with one caller lives in the caller's file.
+
+## Deployment and publishing pipelines
+
+Deployment, publishing, and long-running scripts separate validation, planning, confirmation,
+execution, readiness checks, and cleanup.
+
+- Fail before any work when the script lacks a required input, command, file, host, or secret.
+- Name the target explicitly: never infer production, a remote, a host, or an artifact from a
+  branch name without a confirmation or a CI contract.
+- A destructive or remote action asks for confirmation unless CI owns the guard.
+- Use idempotent commands and stop at the first failed required step.
+- Check readiness after deploying or publishing, and print diagnostics a person can act on.
+- Keep rollback and cleanup explicit, and delete no artifact or result as a side effect.
+- Log enough to reconstruct what happened, without secrets.
+
+```bash
+# confirm_exact: Requires the user to type the expected value.
+# Arguments:
+#   Prompt label.
+#   Expected response.
+confirm_exact() {
+  local label="$1"
+  local expected="$2"
+  local response
+
+  printf '%s Type %s to continue: ' "${label}" "${expected}" >&2
+  IFS= read -r response
+
+  [[ "${response}" == "${expected}" ]]
+}
+```
+
+## Remote commands
+
+Copy a reviewed script to the remote host and invoke it with arguments. SSH joins its arguments
+into one remote shell string, so local quoting does not keep remote argument boundaries. Validate
+host, user, service, and path values before using them, never build a remote command from user
+input, and give every remote call that can hang a timeout.
+
+Good, for a remote Bash login shell:
+
+```bash
+printf -v remote_command 'bash -- %q %q %q' "${remote_script}" "${dir}" "${service}"
+ssh -- "${host}" "${remote_command}"
+```
+
+## Persisted state
+
+Never `source` generated state or pass it to `bash -c`. Write state in a fixed data format with an
+exact key schema to a restricted file in the destination folder, and replace the previous state
+with an atomic `mv`. A reader treats a malformed, duplicate, or unknown key as an error.
+
+## Retries
+
+Retry only an operation known to converge, such as a network pull or readiness polling, with a
+bounded number of attempts. A retry never masks corrupt data, invalid credentials, a failed
+migration, a syntax error, or a permission problem. Capture the status in the `else` branch,
+because an `if` whose condition fails and that has no `else` returns zero:
+
+```bash
+if "$@"; then
+  return 0
+else
+  status=$?
+fi
+```

package/configurations/language/bash/rules/SAFETY.md

@@ -0,0 +1,222 @@
+# Bash Safety
+
+## Calling commands
+
+Use fixed command names with argument arrays, never strings built from input, and a script
+never passes untrusted input to a shell. Never use `bash -lc` in repository scripts, and a
+function that runs a caller-supplied command takes the command and its arguments after
+`shift` and invokes `"$@"`.
+
+Check uncommon commands with `command -v` before a long-running, destructive, publishing, or
+error-handling path depends on them. Prefer builtins and parameter expansion to external
+commands for string and arithmetic work, and pass files directly rather than through
+`cat`. Never run `su -c` without the target user.
+
+```bash
+# require_command: Ensures a command exists on PATH.
+# Arguments:
+#   Command name.
+require_command() {
+  local command_name="$1"
+
+  if ! command -v "${command_name}" >/dev/null 2>&1; then
+    printf 'error: required command not found: %s\n' "${command_name}" >&2
+    return 1
+  fi
+}
+```
+
+## Processes and privilege
+
+Treat process names as advisory information, never authorization. Stop and restart paths stop only
+process ids recorded by the owning script family, found through the service manager, a `PID` file, or
+`pgrep -x`, never `ps | grep`. A script that starts background jobs saves each `PID`, waits for
+each, captures each status, and writes per-job output to separate files. It bounds its
+fan-out and kills owned children on `INT`, `TERM`, and `EXIT`. `sudo command > file` redirects
+as the current user, and a glob in `sudo command /path/*` expands before `sudo` runs.
+Privileged writes go through `sudo tee`, and keep a privileged shell string as a fixed literal
+with no input.
+
+```bash
+generate_config | sudo tee /etc/service/config >/dev/null
+
+# run_remote_checks: Runs remote checks and returns non-zero on any failure.
+# Arguments:
+#   Small, already bounded host list to check.
+run_remote_checks() {
+  local host
+  local pid
+  local status=0
+
+  trap 'cleanup_children' EXIT
+  trap 'cleanup_children; exit 130' INT
+  trap 'cleanup_children; exit 143' TERM
+
+  for host in "$@"; do
+    check_host "${host}" >"${work_dir}/${host}.log" 2>&1 &
+    child_pids+=( "$!" )
+  done
+
+  for pid in "${child_pids[@]}"; do
+    wait "${pid}" || status=1
+  done
+
+  trap - EXIT INT TERM
+  return "${status}"
+}
+```
+
+## Structured data
+
+Use parameter expansion for string edits. JSON goes through `jq`, and YAML through `yq` or
+a project-owned parser. Never parse JSON, YAML, XML, HTML, plist, or xcodebuild output
+with ad hoc `grep | sed | awk` unless the script controls the input and the format has no complex structure.
+Prefer machine output modes such as JSON, `NUL`, or explicit format flags and never parse process lists,
+pretty tables, progress bars, or localized text by fixed field numbers. Quote `tr` character
+classes and pin `LC_ALL=C` when converting case. macOS and GNU `sed -i` differ; a committed
+script rewrites through a temporary file unless its documentation restricts it to one platform.
+
+```bash
+# get_service_url: Prints a required nonempty service URL from JSON configuration.
+get_service_url() {
+  local config_file="${1:?Configuration file is required}"
+  local service_url
+
+  service_url="$(jq -er '.service.url | select(type == "string" and length > 0)' "${config_file}")" || return 1
+  printf '%s\n' "${service_url}"
+}
+```
+
+## Network
+
+Downloads use `curl --fail --show-error --silent --location` into an explicit file, with
+tool-native timeouts such as `--connect-timeout` plus `--max-time`, or SSH `ConnectTimeout`, rather
+than GNU `timeout`, which macOS lacks. Download executable content, verify it against an
+independently obtained checksum or signature, and only then run it.
+
+```bash
+installer="${work_dir}/install.sh"
+curl --fail --show-error --silent --location \
+  --connect-timeout 10 \
+  --max-time 60 \
+  --output "${installer}" \
+  "${installer_url}" || exit 1
+printf '%s  %s\n' "${expected_sha256}" "${installer}" | shasum -a 256 -c - || exit 1
+bash "${installer}" --version "${tool_version}"
+
+ssh -o ConnectTimeout=10 -o ServerAliveInterval=15 -o ServerAliveCountMax=2 \
+  -- "${host}" systemctl is-active --quiet "${service_name}"
+```
+
+## Secrets and environment
+
+Keep `set -x` away from secrets. An indirect expansion `${!name}` takes only a validated name.
+
+```bash
+# require_env: Ensures an environment variable is set and non-empty.
+# Arguments:
+#   Environment variable name.
+require_env() {
+  local name="$1"
+
+  if [[ ! "${name}" =~ ^[A-Z_][A-Z0-9_]*$ ]]; then
+    printf 'error: invalid env var name\n' >&2
+    return 1
+  fi
+  if [[ -z "${!name:-}" ]]; then
+    printf 'error: %s is required\n' "${name}" >&2
+    return 1
+  fi
+}
+```
+
+## Temporary files, locks, and cleanup
+
+Temporary paths come from `mktemp` or `mktemp -d` under the system or an explicit project
+temp directory, never from predictable names. Register cleanup immediately after creation.
+Put downloaded, copied, or generated content in a temporary file, validate it with the real
+parser, and replace the destination with `mv`. The file keeps the restrictive permissions
+`mktemp` gave it unless deployment needs others. Remove failed artifacts unless the script
+documents keeping them. Acquire locks atomically with a `mkdir` lock directory holding
+the owner `PID` or with `noclobber` redirection, never with a `test` followed by a create.
+
+Stop commands remove only what the script created. Validate a cleanup path from
+input or persistent state against its permitted root. Reject empty values, `/`,
+the repository root, `$HOME`, symlinks, and anything outside the owner. Keep a `mktemp -d` result
+exactly. Never widen the path to its neighbors. `|| true` never follows a destructive
+command or a required installation, publishing, build, or runtime command.
+
+```bash
+downloaded_file="$(mktemp "${config_file}.XXXXXX")" || exit 1
+trap 'rm -f -- "${downloaded_file}"' EXIT
+curl --fail --show-error --silent --location --output "${downloaded_file}" "${config_url}" || exit 1
+jq empty "${downloaded_file}" >/dev/null || exit 1
+mv -- "${downloaded_file}" "${config_file}" || exit 1
+trap - EXIT
+
+if ! mkdir "${lock_dir}"; then
+  printf 'error: lock is already held: %s\n' "${lock_dir}" >&2
+  return 1
+fi
+printf '%s\n' "$$" >"${lock_dir}/pid" || {
+  rmdir "${lock_dir}"
+  return 1
+}
+trap 'rm -f -- "${lock_dir}/pid"; rmdir -- "${lock_dir}"' EXIT
+```
+
+Put recursive deletes in one script, and accept that script with an `[[ignore]]` record for `bash/safety`.
+Validate its cleanup path against the owner root:
+
+```bash
+# remove_build_dir: Removes the build child of the approved owner directory.
+remove_build_dir() {
+  local owner_root build_dir
+
+  [[ -n "$1" ]] || return 1
+  owner_root="$(cd -- "$1" && pwd -P)" || return 1
+  [[ "${owner_root}" != / ]] || return 1
+  build_dir="${owner_root}/build"
+  [[ -d "${build_dir}" && ! -L "${build_dir}" ]] || return 1
+  rm -rf -- "${build_dir}"
+}
+```
+
+## Portability
+
+macOS and BSD
+differ from GNU in `sed`, `date`, `readlink`, `mktemp`, `stat`, `xargs`, and `grep`; keep a
+platform-specific branch with the operation that owns it. Handle `realpath` and `date`
+parsing differences. macOS `/bin/bash` uses an old Bash version,
+Linux-only utilities need checks in macOS-compatible scripts, and CI does not share the
+developer's `PATH`. Symlink-aware absolute paths come from `pwd -P` after `cd`, or from
+product-owned application code.
+
+## Verification and debugging
+
+Run the configured syntax, ShellCheck, and shfmt commands. Run destructive or provider tests
+only in a throwaway environment.
+
+Production scripts gain no test-only flags, branches, or command replacements. When
+debugging, start from the exact error and line Bash reports, run `bash -n` and ShellCheck,
+reduce to the smallest reproducing block, and expose invisible characters with
+`printf '%q\n'`. Trace with `bash -x` or a local `set -x` block with a `PS4` naming file, line, and function,
+only while diagnosing, never around secrets, and never commit broad tracing, `trap DEBUG`, or stepping
+code. Bash 4.4 supports `BASH_XTRACEFD`. A debug helper preserves the status it diagnoses.
+
+Common causes follow. `unexpected EOF` indicates an unmatched quote, an unterminated here document,
+a missing `fi`, `done`, or `esac`, or a CRLF ending hiding the delimiter.
+
+`too many arguments` indicates an unquoted expansion inside `[ ... ]`. `event not found` indicates interactive history expansion
+of `!`. Use `type -a` to find an alias, function, builtin, or `PATH` collision when a command behaves differently.
+Failure before the shebang indicates a byte order mark (BOM) or CRLF.
+
+## Refactoring existing scripts
+
+Read the whole script and its sourced libraries, identify the caller interface: local, CI,
+remote host, or package script, and preserve behavior before changing style. Fix quoting and
+argument arrays near the touched logic, and add explicit checks around dangerous commands.
+Share a helper across the script family only when it has a real shared contract. Do not
+convert a large script in one pass or change shebangs across a family without verifying the
+runtime. Run the narrow shell lint and format command before the broader checks. Move complex script
+logic into application code and call it directly.

package/configurations/language/bash/semgrep/bash.yml

@@ -0,0 +1,30 @@
+rules:
+    - id: gspot.bash.curl-pipe-shell
+      languages:
+          - bash
+      severity: ERROR
+      message: A script is downloaded and run in one step; nobody can read what runs.
+          Download it to a file, check it, then run it.
+      pattern-either:
+          - pattern: curl ... | sh ...
+          - pattern: curl ... | sudo sh ...
+          - pattern: sh <(curl ...)
+          - pattern: sh -c "$(curl ...)"
+          - pattern: curl ... | bash ...
+          - pattern: curl ... | sudo bash ...
+          - pattern: bash <(curl ...)
+          - pattern: bash -c "$(curl ...)"
+          - pattern: wget ... | sh ...
+          - pattern: wget ... | sudo sh ...
+          - pattern: sh <(wget ...)
+          - pattern: sh -c "$(wget ...)"
+          - pattern: wget ... | bash ...
+          - pattern: wget ... | sudo bash ...
+          - pattern: bash <(wget ...)
+          - pattern: bash -c "$(wget ...)"
+    - id: gspot.bash.eval
+      languages:
+          - bash
+      severity: ERROR
+      message: eval runs a string as code; build the command as an array instead.
+      pattern: eval ...