imgstat 1.0.3 → 2.0.0

package/README.md

@@ -0,0 +1,27 @@
+# imgstat
+
+imgstat is a CLI tool that embeds image dimensions directly into filenames, or analyzes remote imagery, to give AI context without needing external parsers.
+
+## Features
+
+imgstat handles renaming smoothly and idempotently—it will never re-append dimensions to a file that already has them. When dealing with remote imagery from URLs or scanning your codebase, it securely generates dimension reports without leaving permanent downloads on your machine. For AI integration, the `analyze` mode seamlessly builds an `.agent/rules/image_dimensions.md` file, giving your local language models instant, zero-config context about the images used in your project.
+
+## Usage
+
+Run `imgstat` with no arguments to get an interactive menu. You will be prompted to select the mode you want to use.
+
+```bash
+imgstat
+```
+
+## Contribution Rules
+
+Keep the tool small. If you are considering adding a feature, ask: **does this help AI understand images faster?** If the answer is not clearly yes, it probably does not belong here.
+
+**Every file in `lib/` must have one clear responsibility.** If you find yourself writing image discovery logic inside `rename.sh`, stop and move it to `scan.sh`.
+
+**No feature should require memorizing new flags.** If it can be handled by a mode or an interactive prompt, prefer that.
+
+**Remote mode must never leave files on disk.** The `trap` cleanup is non-negotiable.
+
+**Dry-run must work for any operation that touches files.** This is a safety contract with users.

package/bin/imgstat

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+
+set -e
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR="$DIR/../lib"
+
+source "$LIB_DIR/utils.sh"
+
+# Ensure identify is available
+require_command identify
+
+# Parse global flags and modes
+MODE=""
+TARGET=""
+DRY_RUN="false"
+YES_FLAG="false"
+
+# Simple parser
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    inspect|rename|remote|analyze)
+      if [[ -n "$MODE" ]]; then
+        echo "Error: Multiple modes specified ($MODE and $1)."
+        exit 1
+      fi
+      MODE="$1"
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN="true"
+      shift
+      ;;
+    --yes|-y)
+      YES_FLAG="true"
+      shift
+      ;;
+    --help|-h)
+      echo "imgstat — Embed image dimensions directly into filenames."
+      echo "Usage: imgstat [mode] [target] [options]"
+      echo ""
+      echo "Modes:"
+      echo "  (none)     Interactive menu"
+      echo "  inspect    Print dimensions of local directory images"
+      echo "  rename     Rename local files (e.g. image-800x600.jpg)"
+      echo "  remote     Print dimensions of images from a URL"
+      echo "  analyze    Scan codebase for URLs, write to .agent/rules/image_dimensions.md"
+      echo ""
+      echo "Options:"
+      echo "  --dry-run  Show what would happen without making changes"
+      echo "  --yes, -y  Skip confirmation prompts (for rename)"
+      echo "  --help, -h Show this help message"
+      exit 0
+      ;;
+    -*)
+      echo "Unknown flag: $1"
+      exit 1
+      ;;
+    *)
+      if [[ -z "$TARGET" ]]; then
+        TARGET="$1"
+      else
+        echo "Error: Unexpected argument: $1"
+        exit 1
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [[ -z "$MODE" ]]; then
+  if [[ -n "$TARGET" ]]; then
+    echo "Error: A target was provided without a mode."
+    echo "Usage: imgstat [mode] [target] [--dry-run] [--yes]"
+    exit 1
+  fi
+  source "$LIB_DIR/ui.sh"
+  cmd_ui
+  exit 0
+fi
+
+# Fallback target if none provided
+if [[ "$MODE" == "inspect" || "$MODE" == "rename" || "$MODE" == "analyze" ]]; then
+  TARGET="${TARGET:-./}"
+fi
+
+case "$MODE" in
+  inspect)
+    source "$LIB_DIR/inspect.sh"
+    cmd_inspect "$TARGET"
+    ;;
+  rename)
+    source "$LIB_DIR/rename.sh"
+    cmd_rename "$TARGET" "$DRY_RUN" "$YES_FLAG"
+    ;;
+  remote)
+    if [[ -z "$TARGET" ]]; then
+      echo "Error: URL target required for remote mode."
+      exit 1
+    fi
+    source "$LIB_DIR/remote.sh"
+    cmd_remote "$TARGET" "$DRY_RUN"
+    ;;
+  analyze)
+    source "$LIB_DIR/analyze.sh"
+    cmd_analyze "$TARGET"
+    ;;
+esac

package/build_deb.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+PACKAGE_NAME="imagestat"
+VERSION="1.0"
+ARCH="all"
+DEB_DIR="${PACKAGE_NAME}_${VERSION}_${ARCH}"
+
+echo "Building .deb package for $PACKAGE_NAME..."
+
+# Create directory structure
+mkdir -p "$DEB_DIR/usr/local/bin"
+mkdir -p "$DEB_DIR/DEBIAN"
+
+# Determine source file (handle rename)
+if [ -f "imagestat" ]; then
+    cp imagestat "$DEB_DIR/usr/local/bin/$PACKAGE_NAME"
+elif [ -f "imgstat.sh" ]; then
+    cp imgstat.sh "$DEB_DIR/usr/local/bin/$PACKAGE_NAME"
+else
+    echo "Error: Source script not found (looked for 'imagestat' and 'imgstat.sh')."
+    exit 1
+fi
+
+chmod 755 "$DEB_DIR/usr/local/bin/$PACKAGE_NAME"
+
+# Create control file
+cat > "$DEB_DIR/DEBIAN/control" <<EOF
+Package: $PACKAGE_NAME
+Version: $VERSION
+Section: utils
+Priority: optional
+Architecture: $ARCH
+Allowed-Architectures: all
+Maintainer: User <user@example.com>
+Depends: imagemagick, wget
+Description: Image dimensions scanner and renamer
+ Recursively scans directories for images and renames them to include their 
+ dimensions (e.g., image-800x600.jpg). Ignores heavy directories like node_modules.
+EOF
+
+# Build package
+dpkg-deb --build "$DEB_DIR"
+
+# Cleanup
+mv "${DEB_DIR}.deb" "${PACKAGE_NAME}.deb" 2>/dev/null || true
+rm -rf "$DEB_DIR"
+
+echo "Build complete: ${PACKAGE_NAME}.deb"
+echo "Install with: sudo apt install ./$PACKAGE_NAME.deb"

package/imagestat

@@ -26,11 +26,54 @@ if [ ! -d "$TARGET_DIR" ]; then
     mkdir -p "$TARGET_DIR"
 fi
 
+# Download images if URL is provided
 # Download images if URL is provided
 if [ -n "$URL" ]; then
-    echo "Downloading images from $URL to $TARGET_DIR..."
-    wget -nd -r -P "$TARGET_DIR" -A jpeg,jpg,bmp,gif,png,webp,svg "$URL" 2>/dev/null
-    echo "Download complete."
+    echo "Downloading images from $URL to temp folder..."
+    TEMP_DIR=$(mktemp -d)
+    
+    # Download with wget (no extension restriction to catch all images)
+    # -nd: no directories (flatten)
+    # -r: recursive (useful if URL is a directory, but works for single file too)
+    # -l 1: limit recursion depth to 1 just in case (optional, but safer)
+    # --no-parent: don't go up
+    wget -nd -H -P "$TEMP_DIR" -e robots=off --user-agent="Mozilla/5.0" "$URL" 2>/dev/null
+    
+    echo "Processing downloaded files..."
+    shopt -s nullglob
+    for f in "$TEMP_DIR"/*; do
+        if [ -f "$f" ]; then
+            # Identify format and dimensions (take first frame for animated gifs etc)
+            # Use -ping to be faster? identification doesn't need full read usually
+            ID_OUTPUT=$(identify -format "%m %w %h" "$f[0]" 2>/dev/null)
+            
+            if [ -n "$ID_OUTPUT" ]; then
+                read -r TYPE W H <<< "$ID_OUTPUT"
+                
+                # Normalize extension
+                EXT=$(echo "$TYPE" | tr '[:upper:]' '[:lower:]')
+                case "$EXT" in
+                    jpeg) EXT="jpg" ;;
+                esac
+                
+                # Get clean basename (remove query params)
+                BASENAME=$(basename "$f")
+                CLEAN_NAME=$(echo "$BASENAME" | sed 's/[?=&].*//')
+                # Remove existing extension if it matches common ones
+                CLEAN_NAME="${CLEAN_NAME%.*}"
+                
+                # Construct new filename
+                NEW_FILENAME="${CLEAN_NAME}-${W}x${H}.${EXT}"
+                NEW_PATH="$TARGET_DIR/$NEW_FILENAME"
+                
+                # Move to target
+                mv -n "$f" "$NEW_PATH"
+                echo "Saved: $NEW_FILENAME ($W x $H)"
+            fi
+        fi
+    done
+    rm -rf "$TEMP_DIR"
+    echo "Download processing complete."
 fi
 
 # Export function so xargs can use it

package/install.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+
+APP_NAME="imagestat"
+INSTALL_DIR="/usr/local/bin"
+TARGET_PATH="$INSTALL_DIR/$APP_NAME"
+SOURCE_FILE=""
+
+# Colors
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo -e "${GREEN}Installing $APP_NAME...${NC}"
+
+# Check sudo
+if [ "$EUID" -ne 0 ]; then 
+  echo -e "${YELLOW}Please run as root (sudo) to install globally.${NC}"
+  echo "Try: sudo ./install.sh"
+  exit 1
+fi
+
+# Locate source file
+if [ -f "imagestat" ]; then
+    SOURCE_FILE="imagestat"
+elif [ -f "imgstat.sh" ]; then
+    SOURCE_FILE="imgstat.sh"
+else
+    echo "Local script not found. Downloading from GitHub..."
+    REMOTE_URL="https://raw.githubusercontent.com/isaac0yen/imgstat/main/imagestat"
+    if command -v curl &> /dev/null; then
+        curl -fsSL "$REMOTE_URL" -o imagestat
+    elif command -v wget &> /dev/null; then
+        wget -q "$REMOTE_URL" -O imagestat
+    else
+        echo -e "${RED}Error: Neither curl nor wget found. Cannot download script.${NC}"
+        exit 1
+    fi
+    
+    if [ ! -f "imagestat" ]; then
+         echo -e "${RED}Error: Failed to download script.${NC}"
+         exit 1
+    fi
+    SOURCE_FILE="imagestat"
+fi
+
+# Check dependencies
+MISSING_DEPS=0
+if ! command -v identify &> /dev/null; then
+    echo -e "${RED}Error: 'identify' (ImageMagick) is not installed.${NC}"
+    MISSING_DEPS=1
+fi
+if ! command -v wget &> /dev/null; then
+    echo -e "${RED}Error: 'wget' is not installed.${NC}"
+    MISSING_DEPS=1
+fi
+
+if [ $MISSING_DEPS -eq 1 ]; then
+    echo -e "${YELLOW}Please install missing dependencies first.${NC}"
+    exit 1
+fi
+
+echo "Installing $SOURCE_FILE to $TARGET_PATH..."
+cp "$SOURCE_FILE" "$TARGET_PATH"
+chmod +x "$TARGET_PATH"
+
+echo -e "${GREEN}Success! $APP_NAME has been installed.${NC}"
+echo -e "Usage: ${GREEN}$APP_NAME [-u|--url <url>] [directory]${NC}"

package/lib/analyze.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/utils.sh"
+
+cmd_analyze() {
+  local dir="$1"
+  echo "Analyzing codebase for remote image references in $dir..."
+  
+  # Scan common code files for URLs
+  # We extract http/https links specifically in src, href, url() contexts
+  local urls=()
+  
+  # Read all matching files, use grep to find URLs, and sort uniquely
+  # This uses a basic grep regex to find common image URL patterns.
+  mapfile -t urls < <(find "$dir" \
+    -type d \( -name "node_modules" -o -name ".git" -o -name "dist" -o -name "build" \) -prune -o \
+    -type f \( -name "*.html" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.js" -o -name "*.ts" -o -name "*.vue" -o -name "*.css" -o -name "*.scss" \) \
+    -exec grep -oE "https?://[^\"')[:space:]]+" {} + 2>/dev/null | sort -u)
+
+  if [[ ${#urls[@]} -eq 0 ]]; then
+    echo "No remote URLs found in code files."
+    return 0
+  fi
+  
+  echo "Found ${#urls[@]} unique URL(s). Fetching dimensions..."
+  
+  # Prepare secure fetch directory
+  local TEMP_DIR
+  TEMP_DIR=$(mktemp -d)
+  trap 'rm -rf "$TEMP_DIR"' EXIT
+  
+  # Output file setup
+  local rules_dir="$dir/.agent/rules"
+  local rules_file="$rules_dir/image_dimensions.md"
+  
+  mkdir -p "$rules_dir"
+  
+  # Write header for the agent
+  cat << 'EOF' > "$rules_file"
+# Codebase Remote Images
+
+> [!NOTE]
+> This file is strictly auto-generated by \`imgstat\`.
+> It maps remote image URLs found in the codebase to their exact physical dimensions.
+> AI assistants should use this dictionary when asked about layout constraints, native sizes, or aspect ratios of referenced images.
+
+| Documented URL | Detected Size (W x H) |
+|---|---|
+EOF
+  
+  local processed=0
+  
+  for url in "${urls[@]}"; do
+    # Skip obvious non-images if possible, but Cloudinary etc don't have extensions
+    # so we attempt a shallow fetch for all to be safe.
+    
+    # 1. Fetch direct URL
+    wget -q --content-disposition -P "$TEMP_DIR" "$url" || true
+    
+    local all_files=( "$TEMP_DIR"/* )
+    local found_images=()
+    
+    for file in "${all_files[@]}"; do
+      if [[ ! -f "$file" ]]; then continue; fi
+      local mimetype
+      mimetype=$(file -b --mime-type "$file" 2>/dev/null || true)
+      if [[ "$mimetype" == image/* ]]; then
+        found_images+=("$file")
+      fi
+    done
+    
+    # Process only the first valid image found for the URL
+    if [[ ${#found_images[@]} -gt 0 ]]; then
+      local file="${found_images[0]}"
+      local dim
+      dim=$(get_dimensions "$file" || true)
+      
+      if [[ -n "$dim" ]]; then
+        local w="${dim% *}"
+        local h="${dim#* }"
+        echo "| \`$url\` | **${w}x${h}** |" >> "$rules_file"
+        processed=$((processed + 1))
+      fi
+    fi
+    
+    # Clean temp dir contents for the next URL to avoid collision
+    rm -rf "${TEMP_DIR:?}"/*
+  done
+  
+  echo "Analysis complete!"
+  echo "Documented $processed valid image reference(s) into: $rules_file"
+  echo "This file can now be read by autonomous coding agents."
+}

package/lib/inspect.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/utils.sh"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scan.sh"
+
+cmd_inspect() {
+  local dir="$1"
+  echo "Inspecting directory: $dir"
+  
+  local files
+  mapfile -t files < <(scan_images "$dir")
+  
+  if [[ ${#files[@]} -eq 0 ]]; then
+    echo "No images found in $dir."
+    return 0
+  fi
+  
+  printf "%-50s | %-15s\n" "Filename" "Dimensions"
+  printf "%.s-" {1..70}
+  echo
+  
+  for file in "${files[@]}"; do
+    local dim
+    dim=$(get_dimensions "$file" || true)
+    if [[ -n "$dim" ]]; then
+      local w="${dim% *}"
+      local h="${dim#* }"
+      printf "%-50s | %s x %s\n" "$(basename "$file")" "$w" "$h"
+    else
+      printf "%-50s | %-15s\n" "$(basename "$file")" "Error reading"
+    fi
+  done
+}

package/lib/remote.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/utils.sh"
+
+cmd_remote() {
+  local url="$1"
+  local dry_run="$2"
+  
+  if [[ "$dry_run" == "true" ]]; then
+    echo "[Dry Run] Would fetch $url to extract dimensions. Nothing will be downloaded."
+    return 0
+  fi
+  
+  echo "Fetching images from $url..."
+  
+  local TEMP_DIR
+  TEMP_DIR=$(mktemp -d)
+  trap 'rm -rf "$TEMP_DIR"' EXIT
+  
+  # 1. Fetch direct URL (handles direct images without extensions like Cloudinary)
+  wget -q --content-disposition -P "$TEMP_DIR" "$url" || true
+  
+  # 2. Shallow scrape for linked images (handles HTML pages)
+  wget -q -nd -r -l 1 -A jpeg,jpg,bmp,gif,png,webp,avif -P "$TEMP_DIR" "$url" || true
+  
+  local all_files=( "$TEMP_DIR"/* )
+  local found_images=()
+  
+  # Filter only actual images
+  for file in "${all_files[@]}"; do
+    if [[ ! -f "$file" ]]; then continue; fi
+    local mimetype
+    mimetype=$(file -b --mime-type "$file" 2>/dev/null || true)
+    if [[ "$mimetype" == image/* ]]; then
+      found_images+=("$file")
+    fi
+  done
+  
+  if [[ ${#found_images[@]} -eq 0 ]]; then
+    echo "No images found at $url."
+    return 0
+  fi
+  
+  printf "%-50s | %-15s\n" "Filename" "Dimensions"
+  printf "%.s-" {1..70}
+  echo
+  
+  for file in "${found_images[@]}"; do
+    local dim
+    dim=$(get_dimensions "$file" || true)
+    if [[ -n "$dim" ]]; then
+      local w="${dim% *}"
+      local h="${dim#* }"
+      printf "%-50s | %s x %s\n" "$(basename "$file")" "$w" "$h"
+    else
+      printf "%-50s | %-15s\n" "$(basename "$file")" "Error reading"
+    fi
+  done
+}

package/lib/rename.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/utils.sh"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scan.sh"
+
+cmd_rename() {
+  local dir="$1"
+  local dry_run="$2" # true or false
+  local auto_yes="$3" # true or false
+  
+  local files
+  mapfile -t files < <(scan_images "$dir")
+  
+  if [[ ${#files[@]} -eq 0 ]]; then
+    echo "No images found in $dir."
+    return 0
+  fi
+  
+  local to_rename=()
+  local new_names=()
+  
+  for file in "${files[@]}"; do
+    local dim
+    dim=$(get_dimensions "$file" || true)
+    if [[ -z "$dim" ]]; then
+      continue
+    fi
+    local w="${dim% *}"
+    local h="${dim#* }"
+    
+    local new_filename
+    new_filename=$(format_filename "$file" "$w" "$h")
+    
+    if [[ -n "$new_filename" ]]; then
+      to_rename+=("$file")
+      new_names+=("$new_filename")
+    fi
+  done
+  
+  if [[ ${#to_rename[@]} -eq 0 ]]; then
+    echo "All images already have dimensions in their filenames. Nothing to do."
+    return 0
+  fi
+  
+  echo "Found ${#to_rename[@]} file(s) to rename:"
+  for i in "${!to_rename[@]}"; do
+    echo "  $(basename "${to_rename[$i]}") -> $(basename "${new_names[$i]}")"
+  done
+  
+  if [[ "$dry_run" == "true" ]]; then
+    echo
+    echo "[Dry Run] No files were changed."
+    return 0
+  fi
+  
+  if [[ "$auto_yes" != "true" ]]; then
+    echo
+    read -r -p "Proceed with renaming? [y/N] " response
+    if [[ ! "$response" =~ ^([yY][eE][sS]|[yY])$ ]]; then
+      echo "Aborted."
+      return 1
+    fi
+  fi
+  
+  for i in "${!to_rename[@]}"; do
+    mv "${to_rename[$i]}" "${new_names[$i]}"
+  done
+  
+  echo "Renaming complete."
+}

package/lib/scan.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+# Recursively find images, ignoring node_modules and .git
+# Usage: scan_images "directory"
+scan_images() {
+  local dir="$1"
+  if [[ ! -d "$dir" ]]; then
+    echo "Error: Directory '$dir' does not exist." >&2
+    exit 1
+  fi
+  
+  # GNU find syntax for ignoring dirs and matching extensions case-insensitively
+  find "$dir" -type d \( -name "node_modules" -o -name ".git" \) -prune \
+    -o -type f \( -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.png" -o -iname "*.gif" -o -iname "*.webp" -o -iname "*.avif" \) -print
+}

package/lib/ui.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/inspect.sh"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/rename.sh"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/remote.sh"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/analyze.sh"
+
+cmd_ui() {
+  local options=("Inspect local directory" "Rename local files" "Analyze remote URL" "Analyze codebase (.agent/rules)" "Quit")
+  local selected=0
+
+  # Hide cursor
+  tput civis
+  
+  while true; do
+    echo -ne "\033[1;36mimgstat\033[0m: The tool for embedding image dimensions in filenames.\n"
+    echo "Select an operation mode (Use Up/Down arrows and Enter):"
+    
+    for i in "${!options[@]}"; do
+      if [[ $i -eq $selected ]]; then
+        echo -e "\033[1;32m> ${options[$i]}\033[0m"
+      else
+        echo "  ${options[$i]}"
+      fi
+    done
+    
+    read -rsn1 key || true
+    if [[ $key == $'\x1b' ]]; then
+      read -rsn2 -t 0.1 seq || true
+      case "$seq" in
+        "[A") # Up arrow
+          ((selected--)) || true
+          if [[ $selected -lt 0 ]]; then selected=$((${#options[@]} - 1)); fi
+          ;;
+        "[B") # Down arrow
+          ((selected++)) || true
+          if [[ $selected -ge ${#options[@]} ]]; then selected=0; fi
+          ;;
+      esac
+    elif [[ $key == "" ]]; then # Enter key
+      # Clear menu lines before proceeding
+      tput cuu $((${#options[@]} + 2))
+      tput ed
+      break
+    fi
+    
+    # Go up and clear to redraw
+    tput cuu $((${#options[@]} + 2))
+    tput ed
+  done
+  
+  # Restore cursor
+  tput cnorm
+  
+  case "$selected" in
+    0)
+      read -e -p "Enter directory to inspect [./]: " dir
+      dir="${dir:-./}"
+      cmd_inspect "$dir"
+      ;;
+    1)
+      read -e -p "Enter directory to rename [./]: " dir
+      dir="${dir:-./}"
+      cmd_rename "$dir" "false" "false"
+      ;;
+    2)
+      read -e -p "Enter URL to analyze: " url
+      if [[ -z "$url" ]]; then
+        echo "URL cannot be empty."
+      else
+        cmd_remote "$url" "false"
+      fi
+      ;;
+    3)
+      read -e -p "Enter codebase directory to analyze [./]: " dir
+      dir="${dir:-./}"
+      cmd_analyze "$dir"
+      ;;
+    4)
+      echo "Exiting."
+      ;;
+  esac
+}

package/lib/utils.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+
+# Check if required command is available
+require_command() {
+  local cmd="$1"
+  if ! command -v "$cmd" &> /dev/null; then
+    echo "Error: Required command '$cmd' is not installed." >&2
+    exit 1
+  fi
+}
+
+# Get Image Dimensions using ImageMagick 'identify'
+# Usage: get_dimensions "file.jpg"
+# Outputs: width height
+get_dimensions() {
+  local file="$1"
+  # -ping is faster because it doesn't read the whole image data if possible
+  if ! dim=$(identify -ping -format "%w %h" "$file" 2>/dev/null); then
+    return 1
+  fi
+  echo "$dim"
+}
+
+# Generate the target filename if it doesn't already have the dimensions
+# Usage: format_filename "file.jpg" "800" "600"
+# Outputs: target_file.jpg (or nothing if it shouldn't be renamed)
+format_filename() {
+  local file="$1"
+  local w="$2"
+  local h="$3"
+  
+  local filename
+  filename=$(basename -- "$file")
+  local ext="${filename##*.}"
+  local name="${filename%.*}"
+  
+  # If file has no extension
+  if [[ "$name" == "$filename" ]]; then
+    ext=""
+  fi
+  
+  local dim_suffix="${w}x${h}"
+  
+  # Check if already ends with -WxH
+  if [[ "$name" == *-*x* ]]; then
+    local current_suffix="${name##*-}"
+    if [[ "$current_suffix" == "$dim_suffix" ]]; then
+      # Already correct
+      return 0
+    fi
+  fi
+  
+  local new_name
+  if [[ -n "$ext" ]]; then
+    new_name="${name}-${dim_suffix}.${ext}"
+  else
+    new_name="${name}-${dim_suffix}"
+  fi
+  
+  local dirname
+  dirname=$(dirname -- "$file")
+  
+  echo "$dirname/$new_name"
+}

package/package.json

@@ -1,30 +1,18 @@
 {
   "name": "imgstat",
-  "version": "1.0.3",
-  "description": "Recursively rename images with dimensions so LLMs can see them.",
-  "bin": {
-    "imgstat": "./imagestat",
-    "imagestat": "./imagestat"
+  "version": "2.0.0",
+  "description": "Embeds image dimensions directly into filenames for natural AI context.",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/isaac0yen/imgstat.git"
+  "bin": {
+    "imgstat": "./bin/imgstat"
   },
+  "license": "MIT",
   "keywords": [
+    "cli",
     "image",
-    "resize",
-    "rename",
     "dimensions",
-    "cli",
-    "bash"
-  ],
-  "author": "Isaac Oyeniyi",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/isaac0yen/imgstat/issues"
-  },
-  "homepage": "https://github.com/isaac0yen/imgstat#readme",
-  "files": [
-    "imagestat"
+    "ai"
   ]
-}
+}