imgstat 3.0.3 → 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/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,13 +5,14 @@ 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)
@@ -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/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.3",
+  "version": "3.1.0",
   "description": "Embeds image dimensions directly into filenames for natural AI context.",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"