imgstat 3.0.2 → 3.1.0

package/README.md

@@ -14,6 +14,26 @@ can actually read — without guessing, without vision tokens, without touching
 npm install -g imgstat
 ```
 
+## usage
+
+imgstat infers your intent automatically based on the target you provide.
+
+```bash
+# Print dimensions of images from a web URL
+imgstat https://example.com/logo.png
+
+# Inspect a local directory
+imgstat ./public/images
+
+# Output strict, flat JSON (ideal for AI parsing)
+imgstat https://example.com/images --json
+
+# Rename local images to append dimensions (e.g., image-800x600.jpg)
+imgstat rename ./public/images -y
+```
+
+When run in non-interactive environments or with flags, imgstat routes all progress logs to standard error, ensuring `stdout` remains clean for pipeline parsing and LLM usage.
+
 ## 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.

package/bin/imgstat

@@ -45,30 +45,36 @@ while [[ $# -gt 0 ]]; do
     --help|-h)
       echo "imgstat — Embed image dimensions directly into filenames."
       echo "Usage: imgstat [mode] [target] [options]"
+      echo "       imgstat <url> [--json]       (Auto-infers remote mode)"
+      echo "       imgstat <path> [--json]      (Auto-infers inspect mode)"
       echo ""
       echo "Modes:"
-      echo "  (none)     Interactive menu"
+      echo "  (none)     Interactive menu (Not recommended for AI agents)"
       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 dimension report for your IDE"
       echo ""
-      echo "Options:"
-      echo "  --format   Set output format (e.g. --format json)"
-      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"
+      echo "Options for AI Agents:"
+      echo "  --json     Output strictly flat JSON to stdout (Recommended)"
+      echo "  --yes, -y  Skip all confirmation prompts"
+      echo "  --dry-run  Safe preview of changes"
+      echo "  --help     Show this help message"
       exit 0
       ;;
     --format)
       shift
       FORMAT="$1"
       if [[ "$FORMAT" != "json" ]]; then
-        echo "Error: unsupported format '$FORMAT'. Only 'json' is supported."
+        echo "Error: unsupported format '$FORMAT'. Only 'json' is supported." >&2
         exit 1
       fi
       shift
       ;;
+    --json)
+      FORMAT="json"
+      shift
+      ;;
     -*)
       echo "Unknown flag: $1"
       exit 1
@@ -87,13 +93,16 @@ 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
+    if [[ "$TARGET" =~ ^https?:// ]]; then
+      MODE="remote"
+    else
+      MODE="inspect"
+    fi
+  else
+    source "$LIB_DIR/ui.sh"
+    cmd_ui
+    exit 0
   fi
-  source "$LIB_DIR/ui.sh"
-  cmd_ui
-  exit 0
 fi
 
 # Fallback target if none provided
@@ -104,7 +113,7 @@ fi
 case "$MODE" in
   inspect)
     source "$LIB_DIR/inspect.sh"
-    cmd_inspect "$TARGET"
+    cmd_inspect "$TARGET" "$FORMAT"
     ;;
   rename)
     source "$LIB_DIR/rename.sh"
@@ -116,7 +125,7 @@ case "$MODE" in
       exit 1
     fi
     source "$LIB_DIR/remote.sh"
-    cmd_remote "$TARGET" "$DRY_RUN"
+    cmd_remote "$TARGET" "$DRY_RUN" "$FORMAT"
     ;;
   analyze)
     source "$LIB_DIR/analyze.sh"

package/lib/analyze.sh

@@ -6,7 +6,7 @@ cmd_analyze() {
   local dir="$1"
   local target_option="${2:-1}"
   local json_format="$3"
-  echo "Analyzing codebase for remote image references in $dir..."
+  echo "Analyzing codebase for remote image references in $dir..." >&2
 
   # ── Step 1: Extract all http/https URLs from common code files ──────────────
   local all_urls=()
@@ -18,12 +18,12 @@ cmd_analyze() {
     -exec grep -hoE "https?://[^\"')[:space:]]+" {} + 2>/dev/null | sort -u)
 
   if [[ ${#all_urls[@]} -eq 0 ]]; then
-    echo "No remote URLs found in code files."
+    echo "No remote URLs found in code files." >&2
     return 0
   fi
 
-  echo "Found ${#all_urls[@]} unique URL(s). Classifying..."
-  echo ""
+  echo "Found ${#all_urls[@]} unique URL(s). Classifying..." >&2
+  echo "" >&2
 
   # ── Step 2: Classify each URL via 3-tier pipeline ──────────────────────────
   local image_extensions=("jpg" "jpeg" "png" "gif" "webp" "avif" "svg" "bmp" "tiff" "tif" "ico")
@@ -39,7 +39,7 @@ cmd_analyze() {
 
     # ── Tier 1: Obvious non-image check (fast, no network) ──────────────────
     if is_obvious_non_image "$url"; then
-      printf "  \033[2m⏭  Skip  (pattern match) : %s\033[0m\n" "$url"
+      printf "  \033[2m⏭  Skip  (pattern match) : %s\033[0m\n" "$url" >&2
       continue
     fi
 
@@ -55,30 +55,30 @@ cmd_analyze() {
     done
 
     if [[ "$is_image_ext" == "true" ]]; then
-      printf "  \033[1;32m✓  Queue (extension)     : %s\033[0m\n" "$url"
+      printf "  \033[1;32m✓  Queue (extension)     : %s\033[0m\n" "$url" >&2
       queued_urls+=("$url")
       continue
     fi
 
     # ── Tier 3: HTTP HEAD Content-Type check (network, no body download) ─────
-    printf "  \033[33m?  Check (HEAD request)  : %s\033[0m" "$url"
+    printf "  \033[33m?  Check (HEAD request)  : %s\033[0m" "$url" >&2
     if check_content_type_is_image "$url"; then
-      printf "\r  \033[1;32m✓  Queue (content-type)  : %s\033[0m\n" "$url"
+      printf "\r  \033[1;32m✓  Queue (content-type)  : %s\033[0m\n" "$url" >&2
       queued_urls+=("$url")
     else
-      printf "\r  \033[2m⏭  Skip  (not image CT)  : %s\033[0m\n" "$url"
+      printf "\r  \033[2m⏭  Skip  (not image CT)  : %s\033[0m\n" "$url" >&2
     fi
   done
 
-  echo ""
+  echo "" >&2
 
   if [[ ${#queued_urls[@]} -eq 0 ]]; then
-    echo "No image URLs found after classification."
+    echo "No image URLs found after classification." >&2
     return 0
   fi
 
-  echo "Fetching dimensions for ${#queued_urls[@]} image URL(s)..."
-  echo ""
+  echo "Fetching dimensions for ${#queued_urls[@]} image URL(s)..." >&2
+  echo "" >&2
 
   # ── Step 3: Download & measure queued image URLs ───────────────────────────
   local TEMP_DIR
@@ -119,7 +119,7 @@ cmd_analyze() {
         local w="${dim% *}"
         local h="${dim#* }"
         echo "${url}|${w}|${h}" >> "$TEMP_RESULTS"
-        printf "  \033[1;32m📐 %s → %sx%s\033[0m\n" "$url" "$w" "$h"
+        printf "  \033[1;32m📐 %s → %sx%s\033[0m\n" "$url" "$w" "$h" >&2
         processed=$((processed + 1))
       fi
     fi
@@ -128,11 +128,11 @@ cmd_analyze() {
     rm -rf "${TEMP_DIR:?}"/*
   done
 
-  echo ""
-  echo "Analysis complete!"
+  echo "" >&2
+  echo "Analysis complete!" >&2
 
   if [[ $processed -eq 0 ]]; then
-    echo "No matching images with dimension info could be parsed."
+    echo "No matching images with dimension info could be parsed." >&2
     return 0
   fi
 
@@ -172,5 +172,5 @@ cmd_analyze() {
       ;;
   esac
 
-  echo "This file can now be read by autonomous coding agents."
+  echo "This file can now be read by autonomous coding agents." >&2
 }

package/lib/detect-ide.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+
+# IDE Detection Script for imgstat
+# Identifies the environment and exports the correct routes for rule generation
+
+# 1. Initialize variables
+IDE_NAME="Generic"
+RULE_PATH="AGENTS.md"
+SUPPORTS_IMAGES=false
+
+# 2. Check for Cursor specifically (it often sets CURSOR_CLI)
+if [[ "$TERM_PROGRAM" == "cursor" ]] || [[ -n "$CURSOR_CLI" ]]; then
+    IDE_NAME="Cursor"
+    RULE_PATH=".cursor/rules/"
+    SUPPORTS_IMAGES=false
+
+# 3. Check for Windsurf
+elif [[ "$TERM_PROGRAM" == "windsurf" ]] || [[ -n "$WINDSURF_CLI" ]]; then
+    IDE_NAME="Windsurf"
+    RULE_PATH=".windsurf/rules/"
+    SUPPORTS_IMAGES=false
+
+# 4. Check for VS Code / GitHub Copilot
+elif [[ "$TERM_PROGRAM" == "vscode" ]]; then
+    IDE_NAME="VS Code"
+    RULE_PATH=".github/copilot-instructions.md"
+    SUPPORTS_IMAGES=false
+
+# 5. Check for Kiro
+elif [[ -n "$KIRO_SESSION_ID" ]] || [[ "$TERM_PROGRAM" == "kiro" ]]; then
+    IDE_NAME="Kiro"
+    RULE_PATH=".kiro/steering/"
+    SUPPORTS_IMAGES=false
+
+# 6. Check for iTerm2 (Good for imgstat image rendering)
+elif [[ "$TERM_PROGRAM" == "iTerm.app" ]] || [[ -n "$ITERM_SESSION_ID" ]]; then
+    IDE_NAME="iTerm2"
+    RULE_PATH=".agents/rules/"
+    SUPPORTS_IMAGES=true
+
+# 7. Check for Apple Terminal
+elif [[ "$TERM_PROGRAM" == "Apple_Terminal" ]]; then
+    IDE_NAME="Apple Terminal"
+    RULE_PATH="AGENTS.md"
+    SUPPORTS_IMAGES=false
+
+# 8. Windows-specific checks (WSL/Git Bash)
+elif [[ -n "$WSLENV" ]] || [[ "$(uname -r)" == *"microsoft"* ]]; then
+    # Check for Cursor on Windows
+    if command -v tasklist.exe &> /dev/null && tasklist.exe 2>/dev/null | grep -qi "Cursor.exe"; then
+        IDE_NAME="Cursor (Windows)"
+        RULE_PATH=".cursor/rules/"
+        SUPPORTS_IMAGES=false
+    # Check for VS Code on Windows
+    elif command -v tasklist.exe &> /dev/null && tasklist.exe 2>/dev/null | grep -qi "Code.exe"; then
+        IDE_NAME="VS Code (Windows)"
+        RULE_PATH=".github/copilot-instructions.md"
+        SUPPORTS_IMAGES=false
+    else
+        IDE_NAME="WSL ($SHELL)"
+        RULE_PATH="AGENTS.md"
+        SUPPORTS_IMAGES=false
+    fi
+
+# 9. Fallback/Standard Check
+else
+    IDE_NAME="Generic Shell ($SHELL)"
+    RULE_PATH="AGENTS.md"
+fi
+
+# Export the results for use in other scripts
+export IMGSTAT_IDE="$IDE_NAME"
+export IMGSTAT_PATH="$RULE_PATH"
+export IMGSTAT_SUPPORTS_IMAGES="$SUPPORTS_IMAGES"
+
+# Return values (for sourcing)
+echo "$IDE_NAME|$RULE_PATH|$SUPPORTS_IMAGES"

package/lib/inspect.sh

@@ -5,19 +5,36 @@ source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scan.sh"
 
 cmd_inspect() {
   local dir="$1"
-  echo "Inspecting directory: $dir"
+  local format="$2"
+  echo "Inspecting directory: $dir" >&2
   
   local files
   mapfile -t files < <(scan_images "$dir")
   
   if [[ ${#files[@]} -eq 0 ]]; then
-    echo "No images found in $dir."
+    echo "No images found in $dir." >&2
     return 0
   fi
   
-  printf "%-50s | %-15s\n" "Filename" "Dimensions"
-  printf "%.s-" {1..70}
-  echo
+  if [[ "$format" == "json" ]]; then
+    local temp_res=$(mktemp)
+    for file in "${files[@]}"; do
+      local dim
+      dim=$(get_dimensions "$file" || true)
+      if [[ -n "$dim" ]]; then
+        local w="${dim% *}"
+        local h="${dim#* }"
+        echo "${file}|${w}|${h}" >> "$temp_res"
+      fi
+    done
+    bash "$(dirname "${BASH_SOURCE[0]}")/format-json.sh" "." "$temp_res" "0"
+    rm -f "$temp_res"
+    return 0
+  fi
+  
+  printf "%-50s | %-15s\n" "Filename" "Dimensions" >&2
+  printf "%.s-" {1..70} >&2
+  echo >&2
   
   for file in "${files[@]}"; do
     local dim
@@ -27,7 +44,7 @@ cmd_inspect() {
       local h="${dim#* }"
       printf "%-50s | %s x %s\n" "$(basename "$file")" "$w" "$h"
     else
-      printf "%-50s | %-15s\n" "$(basename "$file")" "Error reading"
+      printf "%-50s | %-15s\n" "$(basename "$file")" "Error reading" >&2
     fi
   done
 }

package/lib/remote.sh

@@ -5,23 +5,24 @@ source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/utils.sh"
 cmd_remote() {
   local url="$1"
   local dry_run="$2"
+  local format="$3"
   
   if [[ "$dry_run" == "true" ]]; then
-    echo "[Dry Run] Would fetch $url to extract dimensions. Nothing will be downloaded."
+    echo "[Dry Run] Would fetch $url to extract dimensions. Nothing will be downloaded." >&2
     return 0
   fi
   
-  echo "Fetching images from $url..."
+  echo "Fetching images from $url..." >&2
   
   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
+  wget -q --timeout=10 --tries=2 --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
+  wget -q --timeout=10 --tries=2 -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=()
@@ -37,13 +38,30 @@ cmd_remote() {
   done
   
   if [[ ${#found_images[@]} -eq 0 ]]; then
-    echo "No images found at $url."
+    echo "No images found at $url." >&2
     return 0
   fi
   
-  printf "%-50s | %-15s\n" "Filename" "Dimensions"
-  printf "%.s-" {1..70}
-  echo
+  if [[ "$format" == "json" ]]; then
+    local temp_res=$(mktemp)
+    for file in "${found_images[@]}"; do
+      local dim
+      dim=$(get_dimensions "$file" || true)
+      if [[ -n "$dim" ]]; then
+        local w="${dim% *}"
+        local h="${dim#* }"
+        # Provide base filename since it matches expected JSON output
+        echo "$(basename "$file")|${w}|${h}" >> "$temp_res"
+      fi
+    done
+    bash "$(dirname "${BASH_SOURCE[0]}")/format-json.sh" "." "$temp_res" "0"
+    rm -f "$temp_res"
+    return 0
+  fi
+  
+  printf "%-50s | %-15s\n" "Filename" "Dimensions" >&2
+  printf "%.s-" {1..70} >&2
+  echo >&2
   
   for file in "${found_images[@]}"; do
     local dim
@@ -53,7 +71,7 @@ cmd_remote() {
       local h="${dim#* }"
       printf "%-50s | %s x %s\n" "$(basename "$file")" "$w" "$h"
     else
-      printf "%-50s | %-15s\n" "$(basename "$file")" "Error reading"
+      printf "%-50s | %-15s\n" "$(basename "$file")" "Error reading" >&2
     fi
   done
 }

package/lib/rename.sh

@@ -12,7 +12,7 @@ cmd_rename() {
   mapfile -t files < <(scan_images "$dir")
   
   if [[ ${#files[@]} -eq 0 ]]; then
-    echo "No images found in $dir."
+    echo "No images found in $dir." >&2
     return 0
   fi
   
@@ -38,26 +38,26 @@ cmd_rename() {
   done
   
   if [[ ${#to_rename[@]} -eq 0 ]]; then
-    echo "All images already have dimensions in their filenames. Nothing to do."
+    echo "All images already have dimensions in their filenames. Nothing to do." >&2
     return 0
   fi
   
-  echo "Found ${#to_rename[@]} file(s) to rename:"
+  echo "Found ${#to_rename[@]} file(s) to rename:" >&2
   for i in "${!to_rename[@]}"; do
-    echo "  $(basename "${to_rename[$i]}") -> $(basename "${new_names[$i]}")"
+    echo "  $(basename "${to_rename[$i]}") -> $(basename "${new_names[$i]}")" >&2
   done
   
   if [[ "$dry_run" == "true" ]]; then
-    echo
-    echo "[Dry Run] No files were changed."
+    echo >&2
+    echo "[Dry Run] No files were changed." >&2
     return 0
   fi
   
   if [[ "$auto_yes" != "true" ]]; then
-    echo
+    echo >&2
     read -r -p "Proceed with renaming? [y/N] " response
     if [[ ! "$response" =~ ^([yY][eE][sS]|[yY])$ ]]; then
-      echo "Aborted."
+      echo "Aborted." >&2
       return 1
     fi
   fi
@@ -66,5 +66,5 @@ cmd_rename() {
     mv "${to_rename[$i]}" "${new_names[$i]}"
   done
   
-  echo "Renaming complete."
+  echo "Renaming complete." >&2
 }

package/lib/ui.sh

@@ -6,6 +6,11 @@ source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/remote.sh"
 source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/analyze.sh"
 
 cmd_ui() {
+  if [ ! -t 0 ]; then
+    echo "Error: Non-interactive terminal detected. Interactive menus are not supported here." >&2
+    echo "Please provide arguments instead. Run 'imgstat --help' for usage." >&2
+    exit 1
+  fi
   local options=("Inspect local directory" "Rename local files" "Analyze remote URL" "Analyze codebase (.agent/rules)" "Quit")
   local selected=0
 

package/lib/utils.sh

@@ -168,3 +168,29 @@ check_content_type_is_image() {
   fi
   return 1
 }
+
+# Detect the current IDE/environment and return detection info
+# Usage: detect_ide
+# Returns: IDE_NAME|RULE_PATH|SUPPORTS_IMAGES
+# Also exports: IMGSTAT_IDE, IMGSTAT_PATH, IMGSTAT_SUPPORTS_IMAGES
+detect_ide() {
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  source "$script_dir/detect-ide.sh"
+}
+
+# Get the IDE-specific rule path for writing output
+# Usage: get_rule_path
+# Returns: The path where rules/context should be written
+get_rule_path() {
+  detect_ide > /dev/null
+  echo "$IMGSTAT_PATH"
+}
+
+# Check if the current environment supports image rendering
+# Usage: supports_image_rendering
+# Returns: 0 (true) if images can be rendered, 1 (false) otherwise
+supports_image_rendering() {
+  detect_ide > /dev/null
+  [[ "$IMGSTAT_SUPPORTS_IMAGES" == "true" ]]
+}

package/llms.txt

@@ -0,0 +1,45 @@
+# imgstat CLI (Agent Reference)
+
+`imgstat` is a specialized tool that extracts dimensions (width and height) from local images or remote URLs to provide context.
+
+> **CRITICAL RULE FOR AI AGENTS:** Always use the `--json` flag to receive structured output. Never run this tool without flags, as the interactive fallback will block execution. Always pass `-y` to skip user prompts on state-mutating commands.
+
+## Usage
+
+```bash
+# Recommended one-shot remote inspection
+npx imgstat https://example.com/image.jpg --json
+
+# Recommended one-shot local inspection 
+npx imgstat ./public/images --json
+
+# Rename all local images to append their dimensions (e.g. image-800x600.jpg)
+npx imgstat rename ./public/images -y
+```
+
+## Available Modes
+If you just pass a single argument path or URL, imgstat will automatically infer `inspect` or `remote` respectively.
+
+- `remote`: Downloads a URL (or shallow scrapes an HTML page) and measures any embedded images. 
+- `inspect`: Scans a specific local directory for images and prints their dimensions.
+- `rename`: Actually modifies files on the file system to append dimensions. (Requires `-y` to bypass confirmation).
+- `analyze`: Scrapes an entire codebase for external URL references and builds a report.
+
+## Required Flags for Autonomous Agents
+- `--json`: (Highly Recommended). Formats output as flat JSON. All logs, spinners, and debug text are routed to `stderr`, leaving only the pure JSON on `stdout`.
+- `-y` or `--yes`: Skip confirmation prompts (vital for `rename`).
+- `--dry-run`: Performs read operations and displays actions it *will* perform without writing.
+
+## Output Schema (When using --json)
+```json
+{
+  "generated_at": "2026-04-17T12:00:00Z",
+  "images": [
+    {
+      "path": "hero-bg.jpg",
+      "width": 1920,
+      "height": 1080
+    }
+  ]
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imgstat",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Embeds image dimensions directly into filenames for natural AI context.",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"