@blundergoat/gruff-ts 0.1.0

package/scripts/npm-publish.sh

@@ -0,0 +1,258 @@
+#!/usr/bin/env bash
+# npm-publish.sh
+#
+# Purpose:
+#   Release gruff-ts to npm with local preflight checks and human confirmation.
+#
+# Usage:
+#   bash scripts/npm-publish.sh
+#
+# Behavior:
+#   1) reads package.json name/version
+#   2) verifies npm authentication
+#   3) checks version lockstep and runs the release preflight gate
+#   4) prints a dry-run publish summary
+#   5) asks for manual confirmation before `npm publish`
+#
+# Exit:
+#   0 if published or explicitly aborted, non-zero on failed auth/preflight/publish.
+#
+# Requirements:
+#   - node, npm
+#   - npm publish authentication:
+#       npm package publishing requires either account 2FA for the publish
+#       prompt or a granular access token with Bypass 2FA enabled.
+#
+#     Preferred token setup for this script:
+#       1. In npmjs.com, open Account -> Access Tokens.
+#       2. Generate a Granular Access Token.
+#       3. Grant read/write access to gruff-ts, or to all packages for the
+#          publishing account.
+#       4. Enable Bypass 2FA for write actions.
+#       5. Either store it in your npm user config:
+#            npm config set //registry.npmjs.org/:_authToken=npm_...
+#            bash scripts/npm-publish.sh
+#
+#          Or keep it out of ~/.npmrc and pass it for this shell only:
+#            export NPM_TOKEN="npm_..."
+#            bash scripts/npm-publish.sh
+#
+#     NODE_AUTH_TOKEN is also accepted for the temporary-token path. The
+#     script writes env tokens to a temporary npm config file and removes it
+#     on exit. Do not commit an .npmrc containing a real token.
+set -euo pipefail
+
+REGISTRY_URL="https://registry.npmjs.org/"
+AUTH_SOURCE=""
+TEMP_NPMRC=""
+PACKAGE_NAME=""
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  bash scripts/npm-publish.sh
+  bash scripts/npm-publish.sh --help
+
+Publishes the current package version to npm after:
+  - npm auth/token validation
+  - scripts/bump-version.sh --check
+  - scripts/preflight-checks.sh
+  - npm publish --dry-run
+
+The final publish still requires an interactive y/N confirmation.
+USAGE
+}
+
+die() {
+  printf 'npm-publish: %s\n' "$*" >&2
+  exit 1
+}
+
+repo_root() {
+  local script_dir
+  script_dir="$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+  CDPATH='' cd -- "$script_dir/.." && pwd
+}
+
+read_package_name() {
+  node -p "require('./package.json').name"
+}
+
+read_package_version() {
+  node -p "require('./package.json').version"
+}
+
+cleanup() {
+  if [[ -n "$TEMP_NPMRC" && -f "$TEMP_NPMRC" ]]; then
+    rm -f -- "$TEMP_NPMRC"
+  fi
+}
+trap cleanup EXIT
+
+print_token_instructions() {
+  local reason="$1"
+
+  printf 'Error: %s\n' "$reason" >&2
+  cat >&2 <<EOF
+
+Publish token setup:
+  1. Go to npmjs.com -> Account -> Access Tokens.
+  2. Generate a Granular Access Token.
+  3. Grant read/write access to ${PACKAGE_NAME}, or to all packages for the
+     publishing account.
+  4. Enable Bypass 2FA for write actions.
+  5. Store the token in your npm user config:
+
+       npm config set //registry.npmjs.org/:_authToken=npm_...
+       bash scripts/npm-publish.sh
+
+     This is simple, but it persists the token in ~/.npmrc.
+
+     To avoid storing the token, pass it for this shell only:
+
+       export NPM_TOKEN="npm_..."
+       bash scripts/npm-publish.sh
+
+     NODE_AUTH_TOKEN works too:
+
+       export NODE_AUTH_TOKEN="npm_..."
+       bash scripts/npm-publish.sh
+
+Do not commit an .npmrc containing a real token.
+EOF
+}
+
+configure_token_from_env() {
+  local token_source=""
+  local token_value=""
+
+  if [[ -n "${NPM_TOKEN:-}" ]]; then
+    token_source="NPM_TOKEN"
+    token_value="$NPM_TOKEN"
+  elif [[ -n "${NODE_AUTH_TOKEN:-}" ]]; then
+    token_source="NODE_AUTH_TOKEN"
+    token_value="$NODE_AUTH_TOKEN"
+  else
+    return 1
+  fi
+
+  TEMP_NPMRC=$(mktemp)
+  chmod 0600 "$TEMP_NPMRC"
+  {
+    printf 'registry=%s\n' "$REGISTRY_URL"
+    printf '//registry.npmjs.org/:_authToken=%s\n' "$token_value"
+  } >"$TEMP_NPMRC"
+
+  export NPM_CONFIG_USERCONFIG="$TEMP_NPMRC"
+  AUTH_SOURCE="$token_source"
+}
+
+has_configured_registry_token() {
+  npm config list 2>/dev/null | grep -Eq '^//registry\.npmjs\.org/:_authToken = \(protected\)$'
+}
+
+trim_output() {
+  tr -d '\r' | awk '{$1=$1; print}'
+}
+
+verify_publish_auth() {
+  local npm_user
+  local tfa_mode
+
+  echo "--- Auth check ---"
+  if configure_token_from_env; then
+    echo "Using ${AUTH_SOURCE} via temporary npm config."
+  fi
+
+  if ! npm_user=$(npm whoami --registry="$REGISTRY_URL" 2>/dev/null); then
+    print_token_instructions "npm is not authenticated for ${REGISTRY_URL}."
+    exit 1
+  fi
+
+  echo "Logged in as: ${npm_user}"
+
+  if [[ -n "$AUTH_SOURCE" ]]; then
+    echo "Publish token source: ${AUTH_SOURCE}"
+    echo "Token must be granular, read/write for ${PACKAGE_NAME}, and Bypass 2FA enabled."
+    echo ""
+    return 0
+  fi
+
+  if has_configured_registry_token; then
+    AUTH_SOURCE="npm user config"
+    echo "Publish token source: ${AUTH_SOURCE}"
+    echo "Token must be granular, read/write for ${PACKAGE_NAME}, and Bypass 2FA enabled."
+    echo ""
+    return 0
+  fi
+
+  if ! tfa_mode=$(npm profile get "two-factor auth" --registry="$REGISTRY_URL" 2>/dev/null | trim_output); then
+    print_token_instructions "unable to verify npm 2FA state and no publish token was supplied."
+    exit 1
+  fi
+
+  if [[ -z "$tfa_mode" ]]; then
+    print_token_instructions "npm did not report an account 2FA mode and no publish token was supplied."
+    exit 1
+  fi
+
+  echo "Account 2FA mode: ${tfa_mode}"
+  if [[ "$tfa_mode" == "disabled" ]]; then
+    print_token_instructions "npm account 2FA is disabled and no publish token was supplied."
+    exit 1
+  fi
+
+  echo "No explicit publish token supplied; npm must complete the publish with an interactive OTP."
+  echo ""
+}
+
+main() {
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    usage
+    exit 0
+  fi
+
+  if [[ "$#" -ne 0 ]]; then
+    usage >&2
+    die "unknown argument: $1"
+  fi
+
+  cd "$(repo_root)"
+  [[ -f package.json ]] || die "package.json not found"
+
+  PACKAGE_NAME="$(read_package_name)" || die "failed to read package.json name"
+  local version
+  version="$(read_package_version)" || die "failed to read package.json version"
+  [[ -n "$PACKAGE_NAME" ]] || die "package.json has no name field"
+  [[ -n "$version" ]] || die "package.json has no version field"
+
+  local publish_args=("--registry=$REGISTRY_URL")
+  if [[ "$PACKAGE_NAME" == @*/* ]]; then
+    publish_args+=(--access public)
+  fi
+
+  echo "Publishing ${PACKAGE_NAME}@${version}"
+  verify_publish_auth
+
+  echo "--- Preflight ---"
+  bash scripts/bump-version.sh --check
+  bash scripts/preflight-checks.sh
+  echo ""
+
+  echo "--- Dry run ---"
+  npm publish --dry-run "${publish_args[@]}"
+  echo ""
+
+  local confirm
+  read -rp "Publish ${PACKAGE_NAME}@${version} to npm? (y/N) " confirm
+  if [[ "$confirm" != "y" && "$confirm" != "Y" ]]; then
+    echo "Aborted."
+    exit 0
+  fi
+
+  npm publish "${publish_args[@]}"
+  echo ""
+  echo "Published: https://www.npmjs.com/package/${PACKAGE_NAME}/v/${version}"
+}
+
+main "$@"

package/scripts/preflight-checks.sh

@@ -0,0 +1,357 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+SCRIPT_DIR="$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(CDPATH='' cd -- "$SCRIPT_DIR/.." && pwd)"
+
+if [[ -t 1 && -z "${NO_COLOR:-}" ]]; then
+  BOLD=$'\033[1m'
+  DIM=$'\033[2m'
+  GREEN=$'\033[32m'
+  RED=$'\033[31m'
+  YELLOW=$'\033[33m'
+  BLUE=$'\033[34m'
+  RESET=$'\033[0m'
+else
+  BOLD=''
+  DIM=''
+  GREEN=''
+  RED=''
+  YELLOW=''
+  BLUE=''
+  RESET=''
+fi
+
+PASS="${GREEN}OK${RESET}"
+FAIL="${RED}FAIL${RESET}"
+SKIP="${YELLOW}SKIP${RESET}"
+ARROW="${BLUE}->${RESET}"
+
+TOTAL=0
+PASSED=0
+FAILED=0
+FAILURES=()
+TMP_FILES=()
+START_TIME=$(date +%s%N)
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/preflight-checks.sh
+
+Runs the local preflight gate:
+  - npm run check (TypeScript compile plus unit tests)
+  - gruff-ts full-project scan
+  - shellcheck for scripts/*.sh when shellcheck is installed
+
+Environment:
+  GRUFF_TS_FAIL_ON   gruff-ts severity that fails static analysis (default: advisory)
+USAGE
+}
+
+cleanup() {
+  local temp_file
+
+  for temp_file in "${TMP_FILES[@]}"; do
+    [[ -f "$temp_file" ]] && rm -f -- "$temp_file"
+  done
+}
+
+trap cleanup EXIT
+
+rule() {
+  printf '  %s\n' "${DIM}--------------------------------------------${RESET}"
+}
+
+elapsed_since() {
+  local started_at="$1"
+  local finished_at
+  local elapsed_ms
+  local seconds
+  local minutes
+  local remainder
+  local frac
+
+  finished_at=$(date +%s%N)
+  elapsed_ms=$(((finished_at - started_at) / 1000000))
+
+  if ((elapsed_ms < 1000)); then
+    printf '%dms' "$elapsed_ms"
+    return
+  fi
+
+  seconds=$((elapsed_ms / 1000))
+  frac=$(((elapsed_ms % 1000) / 100))
+
+  if ((seconds < 60)); then
+    printf '%d.%ds' "$seconds" "$frac"
+    return
+  fi
+
+  minutes=$((seconds / 60))
+  remainder=$((seconds % 60))
+  printf '%dm %02d.%ds' "$minutes" "$remainder" "$frac"
+}
+
+header() {
+  printf '\n'
+  printf '  %sPreflight Check%s\n' "$BOLD" "$RESET"
+  printf '  %s%s%s\n' "$DIM" "$(date '+%Y-%m-%d %H:%M:%S')" "$RESET"
+  rule
+  printf '\n'
+}
+
+step() {
+  local label="$1"
+
+  TOTAL=$((TOTAL + 1))
+  printf '  %s %-36s' "$ARROW" "$label"
+}
+
+pass() {
+  local detail="${1:-}"
+
+  PASSED=$((PASSED + 1))
+  if [[ -n "$detail" ]]; then
+    printf '%s  %s%s%s\n' "$PASS" "$DIM" "$detail" "$RESET"
+  else
+    printf '%s\n' "$PASS"
+  fi
+}
+
+fail() {
+  local label="$1"
+
+  FAILED=$((FAILED + 1))
+  FAILURES+=("$label")
+  printf '%s\n' "$FAIL"
+}
+
+skip() {
+  local reason="${1:-skipped}"
+
+  printf '%s  %s%s%s\n' "$SKIP" "$DIM" "$reason" "$RESET"
+}
+
+indent_output() {
+  while IFS= read -r line; do
+    printf '    %s%s%s\n' "$DIM" "$line" "$RESET"
+  done
+}
+
+run_step() {
+  local label="$1"
+  shift
+
+  local started_at
+  local output
+  local status
+  local elapsed
+
+  step "$label"
+  started_at=$(date +%s%N)
+  output=$("$@" 2>&1)
+  status=$?
+  elapsed=$(elapsed_since "$started_at")
+
+  if ((status == 0)); then
+    pass "${output:+$output }$elapsed"
+  else
+    fail "$label"
+    if [[ -n "$output" ]]; then
+      printf '%s\n' "$output" | tail -20 | indent_output
+    fi
+    printf '    %sexit %d after %s%s\n' "$DIM" "$status" "$elapsed" "$RESET"
+  fi
+
+  return "$status"
+}
+
+make_temp_file() {
+  local suffix="$1"
+  local temp_file
+
+  temp_file=$(mktemp "${TMPDIR:-/tmp}/gruff-ts-preflight.XXXXXX.$suffix") || return 1
+  TMP_FILES+=("$temp_file")
+  printf '%s\n' "$temp_file"
+}
+
+npm_check() {
+  local output
+  local status
+  local tests
+  local passed
+  local failed
+
+  output=$(npm run check 2>&1)
+  status=$?
+
+  if ((status != 0)); then
+    printf '%s\n' "$output"
+    return "$status"
+  fi
+
+  tests=$(printf '%s\n' "$output" | awk '/^# tests / { print $3; exit }')
+  passed=$(printf '%s\n' "$output" | awk '/^# pass / { print $3; exit }')
+  failed=$(printf '%s\n' "$output" | awk '/^# fail / { print $3; exit }')
+
+  if [[ -n "$tests" && -n "$passed" ]]; then
+    printf '%s/%s tests passed' "$passed" "$tests"
+    if [[ -n "$failed" && "$failed" != "0" ]]; then
+      printf ', %s failed' "$failed"
+    fi
+  else
+    printf 'completed'
+  fi
+
+  return 0
+}
+
+gruff_report_summary() {
+  local report_path="$1"
+
+  # shellcheck disable=SC2016
+  node --input-type=module -e '
+import { readFileSync } from "node:fs";
+
+const report = JSON.parse(readFileSync(process.argv[1], "utf8"));
+const summary = report.summary ?? {};
+const score = report.score ?? {};
+const paths = report.paths ?? {};
+const total = Number(summary.total ?? 0);
+const advisory = Number(summary.advisory ?? 0);
+const warning = Number(summary.warning ?? 0);
+const error = Number(summary.error ?? 0);
+const grade = String(score.grade ?? "n/a");
+const composite = Number(score.composite ?? 0).toFixed(1);
+const analysedFiles = Number(paths.analysedFiles ?? 0);
+
+console.log(`${total} findings (advisory=${advisory}, warning=${warning}, error=${error}), ${grade} ${composite}/100, ${analysedFiles} files`);
+' "$report_path"
+}
+
+gruff_ts_check() {
+  local gruff_fail_on="${GRUFF_TS_FAIL_ON:-advisory}"
+  local report_path
+  local error_path
+  local status
+  local summary_status=0
+  local printed=0
+
+  report_path=$(make_temp_file json) || return 1
+  error_path=$(make_temp_file err) || return 1
+
+  ./bin/gruff-ts analyse . --format=json --fail-on="$gruff_fail_on" --no-baseline >"$report_path" 2>"$error_path"
+  status=$?
+
+  if [[ -s "$report_path" ]]; then
+    gruff_report_summary "$report_path"
+    summary_status=$?
+    printed=1
+  fi
+
+  if [[ -s "$error_path" ]]; then
+    if ((printed)); then
+      printf '\n'
+    fi
+    cat "$error_path"
+  fi
+
+  if ((status != 0)); then
+    return "$status"
+  fi
+  return "$summary_status"
+}
+
+shellcheck_check() {
+  local scripts=()
+  local script_path
+  local output
+  local status
+
+  while IFS= read -r -d '' script_path; do
+    scripts+=("$script_path")
+  done < <(find scripts -maxdepth 1 -type f -name '*.sh' -print0 | sort -z)
+
+  if [[ "${#scripts[@]}" -eq 0 ]]; then
+    printf 'no scripts/*.sh files found'
+    return 0
+  fi
+
+  output=$(shellcheck "${scripts[@]}" 2>&1)
+  status=$?
+
+  if ((status == 0)); then
+    printf '%d scripts checked' "${#scripts[@]}"
+  else
+    printf '%s\n' "$output"
+  fi
+
+  return "$status"
+}
+
+summary() {
+  local elapsed
+
+  elapsed=$(elapsed_since "$START_TIME")
+  printf '\n'
+  rule
+  printf '\n'
+
+  if ((FAILED == 0)); then
+    printf '  %sAll %d/%d checks passed%s  %s(%s)%s\n' "$GREEN$BOLD" "$PASSED" "$TOTAL" "$RESET" "$DIM" "$elapsed" "$RESET"
+    printf '\n'
+    return 0
+  fi
+
+  printf '  %s%d/%d checks failed%s  %s(%s)%s\n' "$RED$BOLD" "$FAILED" "$TOTAL" "$RESET" "$DIM" "$elapsed" "$RESET"
+  printf '\n'
+
+  local failure
+  for failure in "${FAILURES[@]}"; do
+    printf '    %s  %s\n' "$FAIL" "$failure"
+  done
+  printf '\n'
+
+  return 1
+}
+
+main() {
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    usage
+    return 0
+  fi
+
+  if [[ "$#" -ne 0 ]]; then
+    printf '%sUnknown argument:%s %s\n' "$RED" "$RESET" "$1" >&2
+    usage >&2
+    return 64
+  fi
+
+  cd "$REPO_ROOT" || return 1
+
+  header
+
+  if [[ ! -x ./bin/gruff-ts ]]; then
+    step "gruff-ts binary"
+    fail "gruff-ts binary"
+    printf '    %s./bin/gruff-ts is missing or not executable%s\n' "$DIM" "$RESET"
+    summary
+    return 127
+  fi
+
+  run_step "TypeScript + tests" npm_check
+
+  run_step "Gruff full-project scan" gruff_ts_check
+
+  if command -v shellcheck >/dev/null 2>&1; then
+    run_step "Shell scripts (shellcheck)" shellcheck_check
+  else
+    step "Shell scripts (shellcheck)"
+    skip "shellcheck not found"
+  fi
+
+  summary
+}
+
+main "$@"

package/scripts/start-dev.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+HOST="${GRUFF_HOST:-127.0.0.1}"
+PORT="${GRUFF_PORT:-8767}"
+PROJECT_ROOT="${GRUFF_PROJECT_ROOT:-$(pwd)}"
+
+npm run start-dev -- --host "$HOST" --port "$PORT" --project-root "$PROJECT_ROOT"