@macrulez/devtoolz 0.2.0 → 0.3.0

package/README.md

@@ -127,30 +127,77 @@ looking for is never touched.
   `.vue` files get an isolated per-file check (same technique as
   `readme-check`'s own virtual-file typechecking) — a plain
   `ts.Program` can't include `.vue` in a whole-project run at all.
+- **`image-hash`** — generates [blurhash](https://blurha.sh) and/or
+  [thumbhash](https://evanw.github.io/thumbhash/) placeholders for raster
+  images (jpg, png, webp, gif, avif, tiff). Takes files and/or
+  directories — several of each, comma-separated too — and `-r` walks
+  subdirectories. Prints to stdout by default; `-o <file>` collects
+  everything into one file, `--per-file` / `--out-dir <dir>` writes a
+  file per image (`photo.jpg` → `photo.jpg.blurhash.txt`, with
+  `--suffix` and `--out-ext` to rename). Formats: `json`, `plain` (just
+  the hash text, no newline), `csv`, and `ts`/`js` modules you can import
+  straight into the app. Besides the two hashes it can produce the
+  dominant color and a tiny PNG preview (`-t all`), accepts `http(s)`
+  URLs and path lists from a file or stdin, and can keep an output file in
+  sync: `--cache` skips unchanged images, `--update --prune` merges into
+  the existing file, `--check` fails with exit code 1 when it is stale
+  (made for CI). `--dry-run` writes nothing and shows the result as a
+  table instead. Uses the native `sharp` library, which devtoolz
+  offers to install on first use — see Requirements.
+- **`full-check`** — runs all thirteen other commands in one sweep, each in
+  its own safe read-only mode — the three that can write to disk
+  (`strip-comments`/`console-strip`/`case-check`) are always called as a
+  preview, `-y`/`--fix` are never passed. One summary table: which
+  commands are clean, which found something, which errored. Since
+  `stale-ts-ignore` is the one command that can make a bare `full-check`
+  noticeably slower, running it with no flags in a real terminal asks
+  first — `--skip stale-ts-ignore` skips both the question and the
+  command, `--no-prompt` runs everything without asking (the default
+  answer either way).
 
 `strip-comments`, `console-strip`, and `case-check` share the same safety
 model: `--dry-run` (or just running with neither `--dry-run` nor `-y`)
 only previews, `-y`/`--yes` is required to actually write anything,
 `--diff` shows a real unified diff per file. `dead-exports`,
 `unused-deps`, `circular-imports`, `exports-doctor`, `readme-check`,
-`empty-catch`, `todo-report`, `scripts-check`, `orphan-tests`, and
-`stale-ts-ignore` are all read-only — none of them ever write anything,
-there's nothing to preview or apply. Every command supports `--json` for
+`empty-catch`, `todo-report`, `scripts-check`, `orphan-tests`,
+`stale-ts-ignore`, and `full-check` are all read-only — none of them ever
+write anything, there's nothing to preview or apply. `image-hash` writes
+files only when you name an output (`-o`, `--per-file`, `--out-dir`) and
+prints to stdout otherwise. Every command supports `--json` for
 machine-readable output.
 
 ## Tone
 
 Not dead silent, not relentlessly jokey either — a small banner and some
 personality when everything comes back clean, nothing cute mixed into the
-actual findings list, which stays in aligned, colored columns (file in
-white, count/tag in dim grey) for quick scanning. Auto-disables (banner,
-color, celebration copy) the moment output isn't a real interactive
-terminal — piped, `CI` set, `NO_COLOR` set — on top of the explicit
-`--quiet`/`--plain` flags.
+actual findings list, which stays in aligned columns for quick scanning.
+
+Output is colored with one palette across every command: file paths in
+cyan with their `:line:column` dimmed, names and kinds in yellow, the
+"N problems found" heading in bold red, what a command would do in bold
+yellow and what it did in bold green, hints dimmed with the flags they
+mention (`-y`, `--dry-run`) picked out in cyan, `✔`/`✖` in the
+`full-check` table in green/red, and the diffs red/green as before.
+
+Color turns itself off the moment output isn't a real interactive
+terminal — piped, `CI` set, `NO_COLOR` set, `TERM=dumb`. `--color` (or
+`FORCE_COLOR=1`) turns it back on anyway, which is what you want for
+`devtoolz … --color | less -R` or a CI log that renders ANSI; `--plain`
+turns color, the banner and the celebration copy all off, and `--quiet`
+only drops the banner and clean-run output. The text is identical with
+and without color — only escape codes are added.
 
 ## Requirements
 
 - Node.js 20+
+- `image-hash` only: the [`sharp`](https://sharp.pixelplumbing.com)
+  image library. It ships prebuilt binaries for the common platforms and
+  is not installed with devtoolz — the first `image-hash` run offers to
+  install it into `~/.devtoolz/deps` (`-y` / `--yes` agrees up front, which
+  is also what you want in CI; without a terminal and without `--yes` the
+  command stops and says so). A `sharp` you already have installed
+  alongside devtoolz is used as-is.
 
 ## Installation
 
@@ -199,6 +246,17 @@ devtoolz scripts-check                         # package.json scripts vs README/
 devtoolz orphan-tests src                      # test files whose source disappeared
 
 devtoolz stale-ts-ignore                       # find @ts-ignore comments suppressing nothing
+
+devtoolz image-hash public/img                 # blurhash + thumbhash of every image, as JSON on stdout
+devtoolz image-hash a.jpg,b.png,photos -r -t blurhash -f csv -o hashes.csv
+devtoolz image-hash public/img -r -f plain --per-file   # photo.jpg.blurhash.txt + photo.jpg.thumbhash.txt
+devtoolz image-hash public/img -r -f ts -t thumbhash -o src/placeholders.ts --name placeholders
+devtoolz image-hash public/img -r --dry-run        # write nothing, show a table of the hashes
+devtoolz image-hash public/img -r -t all --components auto -o hashes.json --cache --update --prune
+devtoolz image-hash public/img -r -o hashes.json --check   # CI: exit 1 if hashes.json is stale
+
+devtoolz full-check                            # run every command, one summary table
+devtoolz full-check --skip stale-ts-ignore     # same, minus the expensive one
 ```
 
 Every command has built-in `--help` — `devtoolz --help` lists every
@@ -382,6 +440,71 @@ Checked 1 @ts-ignore directive.
   src/example.ts:2  @ts-ignore  doesn't suppress anything — the line below it typechecks cleanly without it
 ```
 
+`devtoolz full-check` against a small package with a few real, unrelated
+problems scattered across it:
+
+```
+✖ strip-comments    1 found
+✔ console-strip     clean
+✖ dead-exports      1 found
+✔ case-check        clean
+✔ exports-doctor    clean
+✔ readme-check      clean
+✔ unused-deps       clean
+✔ circular-imports  clean
+✖ empty-catch       1 found
+✔ todo-report       clean
+✖ scripts-check     3 found
+✔ orphan-tests      clean
+✔ stale-ts-ignore   clean
+
+9 clean, 4 found something — see `devtoolz <command> --help` for full detail on any of them.
+```
+
+`devtoolz image-hash public/img -r -f plain --per-file` writing a text file
+per hash next to each image:
+
+```
+🧰 devtoolz
+
+Hashed 2 images.
+
+Wrote 4 files:
+  public/img/hero.jpg.blurhash.txt
+  public/img/hero.jpg.thumbhash.txt
+  public/img/logo.png.blurhash.txt
+  public/img/logo.png.thumbhash.txt
+```
+
+`devtoolz image-hash hero.jpg -t blurhash` printing JSON to stdout, ready to
+pipe or paste:
+
+```json
+{
+  "hero.jpg": {
+    "width": 1600,
+    "height": 900,
+    "blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
+  }
+}
+```
+
+`devtoolz image-hash public/img -r -t blurhash --dry-run` shows what would be
+generated as a table and writes nothing:
+
+```
+┌─────────────────────┬─────────┬──────────────────────────────┐
+│ File                │    Size │ BlurHash                     │
+├─────────────────────┼─────────┼──────────────────────────────┤
+│ public/img/blue.png │ 120×300 │ L704c9gSfQgSf:fRfQfRfQfQfQfQ │
+│ public/img/red.jpg  │ 200×100 │ L6T9R{,YfQ,Y|cjtfQjtfQfQfQfQ │
+└─────────────────────┴─────────┴──────────────────────────────┘
+
+Hashed 2 images.
+
+(dry run — nothing written)
+```
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
 import { runStripComments } from './commands/strip-comments/run.js';
 import { renderStripCommentsReport } from './commands/strip-comments/report.js';
 import { runConsoleStrip } from './commands/console-strip/run.js';
@@ -28,6 +30,12 @@ import { runOrphanTests } from './commands/orphan-tests/run.js';
 import { renderOrphanTestsReport } from './commands/orphan-tests/report.js';
 import { runStaleTsIgnore } from './commands/stale-ts-ignore/run.js';
 import { renderStaleTsIgnoreReport } from './commands/stale-ts-ignore/report.js';
+import { runFullCheck, FULL_CHECK_COMMAND_NAMES, SLOW_FULL_CHECK_COMMAND, } from './commands/full-check/run.js';
+import { renderFullCheckReport } from './commands/full-check/report.js';
+import { runImageHash } from './commands/image-hash/run.js';
+import { renderImageHashReport } from './commands/image-hash/report.js';
+import { DEFAULT_CACHE_FILE, DEFAULT_IMAGE_EXTENSIONS, ImageHashUsageError, OUTPUT_FORMATS, parseComponents, parseExtensions, parseFileList, parseFormat, parseMaxPixels, parseSampleSize, parseTypes, } from './commands/image-hash/core.js';
+import { createStyle } from './format/style.js';
 function wrapText(text, width) {
     const words = text.split(' ');
     const lines = [];
@@ -153,6 +161,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runStripComments({
         paths,
@@ -172,6 +181,7 @@ program
         const text = renderStripCommentsReport(report, {
             quiet: options.quiet,
             plain: options.plain,
+            color: options.color,
             dryRun: options.dryRun,
         });
         if (text)
@@ -195,6 +205,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runConsoleStrip({
         paths,
@@ -215,6 +226,7 @@ program
         const text = renderConsoleStripReport(report, {
             quiet: options.quiet,
             plain: options.plain,
+            color: options.color,
         });
         if (text)
             console.log(text);
@@ -235,6 +247,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runDeadExports({
         paths,
@@ -250,7 +263,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderDeadExportsReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderDeadExportsReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -268,6 +285,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runCircularImports({
         paths,
@@ -284,6 +302,7 @@ program
         const text = renderCircularImportsReport(report, {
             quiet: options.quiet,
             plain: options.plain,
+            color: options.color,
         });
         if (text)
             console.log(text);
@@ -302,6 +321,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((dir, options) => {
     const report = runUnusedDeps({
         dir: resolve(dir),
@@ -315,7 +335,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderUnusedDepsReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderUnusedDepsReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -337,6 +361,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runCaseCheck({
         paths,
@@ -354,7 +379,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderCaseCheckReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderCaseCheckReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -367,13 +396,18 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((dir, options) => {
     const report = runExportsDoctor({ dir: resolve(dir) });
     if (options.json) {
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderExportsDoctorReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderExportsDoctorReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -389,6 +423,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((dir, options) => {
     const report = runReadmeCheck({
         dir: resolve(dir),
@@ -400,7 +435,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderReadmeCheckReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderReadmeCheckReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -417,6 +456,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runEmptyCatch({
         paths,
@@ -429,7 +469,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderEmptyCatchReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderEmptyCatchReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -448,6 +492,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runTodoReport({
         paths,
@@ -462,7 +507,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderTodoReportReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderTodoReportReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -476,6 +525,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((dir, options) => {
     const report = runScriptsCheck({ dir: resolve(dir), files: options.file });
     if (options.json) {
@@ -485,6 +535,7 @@ program
         const text = renderScriptsCheckReport(report, {
             quiet: options.quiet,
             plain: options.plain,
+            color: options.color,
         });
         if (text)
             console.log(text);
@@ -506,6 +557,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runOrphanTests({
         paths,
@@ -522,7 +574,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderOrphanTestsReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderOrphanTestsReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -538,6 +594,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((dir, options) => {
     const report = runStaleTsIgnore({
         dir: resolve(dir),
@@ -553,6 +610,206 @@ program
         const text = renderStaleTsIgnoreReport(report, {
             quiet: options.quiet,
             plain: options.plain,
+            color: options.color,
+        });
+        if (text)
+            console.log(text);
+    }
+    process.exitCode = report.exitCode;
+});
+program
+    .command('image-hash')
+    .description('Generate blurhash/thumbhash placeholders (and dominant color, tiny preview) for raster images — to stdout, one file, or a file per image')
+    .argument('[paths...]', 'image files, directories and http(s) URLs (several allowed, comma-separated too)', [])
+    .option('--cwd <path>', 'root paths are resolved against', process.cwd())
+    .option('-r, --recursive', 'also walk subdirectories of every given directory', false)
+    .option('--files-from <file>', 'read more paths/URLs from a file, one per line (- = stdin, # starts a comment)')
+    .option('--ext <list>', 'comma-separated image extensions to pick up from directories', DEFAULT_IMAGE_EXTENSIONS.join(','))
+    .option('--ignore <glob>', 'extra ignore pattern (repeatable), on top of the built-in defaults', (val, prev) => [...prev, val], [])
+    .option('--no-respect-gitignore', "don't also honor the project's .gitignore")
+    .option('-t, --type <list>', 'what to generate, comma-separated: blurhash, thumbhash, color (dominant), preview (tiny PNG data URI); both = blurhash+thumbhash, all = everything', 'both')
+    .option('--components <XxY|auto>', 'blurhash components, each side 1-9, or auto to pick them by aspect ratio', '4x3')
+    .option('--size <px>', 'longest side the image is scaled down to before hashing (1-100)', '100')
+    .option('--max-pixels <n>', 'refuse images with more pixels than this (0 = no limit; default: sharp limit, ~268 million)')
+    .option('-f, --format <format>', `format of the generated hashes: ${OUTPUT_FORMATS.join(', ')} (plain = just the hash text); --json prints the full report instead`, 'json')
+    .option('--name <identifier>', 'exported constant name for --format ts/js', 'imageHashes')
+    .option('--key-base <dir>', 'make the file keys in the output relative to this directory')
+    .option('--key-prefix <text>', 'text put in front of every file key, e.g. / for URL-style keys')
+    .option('-o, --out <file>', 'write everything into one file instead of stdout')
+    .option('--update', 'merge into the existing -o file instead of replacing it', false)
+    .option('--prune', 'with --update, drop entries whose image no longer exists', false)
+    .option('--per-file', 'write one file per image, next to the image', false)
+    .option('--out-dir <dir>', 'write the per-image files into this directory (implies --per-file)')
+    .option('--suffix <text>', 'per-image file name suffix after the image file name, {type} = blurhash/thumbhash/hash (default: .{type})')
+    .option('--out-ext <ext>', 'per-image file extension (default: by --format, plain = .txt)')
+    .option('--check', 'write nothing; exit 1 if the output files are missing or differ from the images', false)
+    .option('--cache [file]', `skip images that did not change since the last run, remembered in this file (default: ${DEFAULT_CACHE_FILE})`)
+    .option('--concurrency <n>', 'images processed in parallel', '4')
+    .option('--dry-run', 'write nothing — show the result as a table instead', false)
+    .option('-y, --yes', 'install the missing "sharp" image library without asking', false)
+    .option('--json', 'machine-readable output', false)
+    .option('--quiet', 'suppress output when there is nothing to report', false)
+    .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
+    .action(async (paths, options) => {
+    const style = createStyle({ plain: options.plain, color: options.color });
+    const showProgress = !options.json && !options.quiet && Boolean(process.stderr.isTTY) && !options.plain;
+    let progressShown = false;
+    try {
+        const listed = options.filesFrom !== undefined
+            ? parseFileList(readFileSync(options.filesFrom === '-' ? 0 : options.filesFrom, 'utf8'))
+            : [];
+        const report = await runImageHash({
+            paths: [...paths, ...listed],
+            cwd: resolve(options.cwd),
+            types: parseTypes(options.type),
+            recursive: options.recursive,
+            extensions: parseExtensions(options.ext),
+            ignoreGlobs: options.ignore,
+            respectGitignore: options.respectGitignore,
+            components: parseComponents(options.components),
+            size: parseSampleSize(options.size),
+            ...(options.maxPixels !== undefined
+                ? { maxPixels: parseMaxPixels(options.maxPixels) }
+                : {}),
+            format: parseFormat(options.format),
+            exportName: options.name,
+            ...(options.keyBase !== undefined ? { keyBase: options.keyBase } : {}),
+            ...(options.keyPrefix !== undefined ? { keyPrefix: options.keyPrefix } : {}),
+            ...(options.out !== undefined ? { out: options.out } : {}),
+            update: options.update,
+            prune: options.prune,
+            perFile: options.perFile,
+            ...(options.outDir !== undefined ? { outDir: options.outDir } : {}),
+            ...(options.suffix !== undefined ? { suffix: options.suffix } : {}),
+            ...(options.outExt !== undefined ? { outExtension: options.outExt } : {}),
+            check: options.check,
+            ...(options.cache !== undefined
+                ? { cache: options.cache === true ? DEFAULT_CACHE_FILE : String(options.cache) }
+                : {}),
+            concurrency: Math.max(1, Number.parseInt(options.concurrency, 10) || 4),
+            assumeYes: options.yes,
+            dryRun: options.dryRun,
+            ...(showProgress
+                ? {
+                    onProgress: ({ done, total }) => {
+                        if (total < 2)
+                            return;
+                        progressShown = true;
+                        process.stderr.write(`\r${style.info(`Hashing ${done}/${total}`)}`);
+                    },
+                }
+                : {}),
+        });
+        if (progressShown)
+            process.stderr.write('\r\x1b[K');
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else if (report.stdout !== null) {
+            process.stdout.write(report.stdout);
+            for (const error of report.errors)
+                console.error(`${error.file} — ${error.message}`);
+        }
+        else {
+            const text = renderImageHashReport(report, {
+                quiet: options.quiet,
+                plain: options.plain,
+                color: options.color,
+            });
+            if (text)
+                console.log(text);
+        }
+        process.exitCode = report.exitCode;
+    }
+    catch (error) {
+        if (progressShown)
+            process.stderr.write('\r\x1b[K');
+        if (error instanceof ImageHashUsageError) {
+            console.error(`error: ${error.message}`);
+            process.exitCode = 2;
+            return;
+        }
+        throw error;
+    }
+});
+// Only `full-check` ever prompts — every other command here is a single,
+// fast, non-interactive check. `stale-ts-ignore` is the one command a
+// bare `full-check` can turn into a genuinely slow run, so this asks
+// about that ONE command specifically, not a general "run everything?"
+// confirmation. Defaults to running it (Enter alone picks option 1) —
+// matches what happens when there's no TTY to ask at all (see
+// `shouldPrompt` below), so a script and an interactive "just press
+// enter" run behave the same way.
+// Deliberately a SINGLE `question()` call, no retry-on-invalid-input loop
+// — found via real testing that a second `question()` on the same (or
+// even a fresh) `readline/promises` interface can silently lose the
+// answer and hang forever once more than one line was already available
+// on stdin when the first question resolved (a real, reproducible
+// readline quirk with piped/non-interactive input, not something specific
+// to this code). One question, with an explicit default on anything else
+// typed, sidesteps the whole bug class instead of risking it.
+async function promptStaleTsIgnoreChoice() {
+    process.stderr.write('stale-ts-ignore runs a full project typecheck twice — this can take noticeably longer than the other commands on a large project.\n\n' +
+        '  1) Run it anyway (full sweep)\n' +
+        '  2) Skip it for this run\n\n');
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    let answer;
+    try {
+        answer = (await rl.question('Choice [1/2, Enter = 1]: ')).trim();
+    }
+    finally {
+        rl.close();
+    }
+    if (answer === '2')
+        return false;
+    if (answer !== '' && answer !== '1') {
+        process.stderr.write(`(didn't recognize "${answer}" — running it, same as Enter)\n`);
+    }
+    return true;
+}
+program
+    .command('full-check')
+    .description('Runs every other command in its own safe/read-only mode — a full diagnostic sweep, never applies a fix')
+    .argument('[dir]', 'directory every command scans/reads from', '.')
+    .option('--skip <command>', `skip a command by name (repeatable) — valid names: ${FULL_CHECK_COMMAND_NAMES.join(', ')}`, (val, prev) => [...prev, val], [])
+    .option('--no-prompt', "don't ask about stale-ts-ignore even in an interactive terminal — runs it unless --skip already excludes it")
+    .option('--json', 'machine-readable output', false)
+    .option('--quiet', 'suppress output when there is nothing to report', false)
+    .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
+    .action(async (dir, options) => {
+    const skip = new Set(options.skip);
+    const shouldPrompt = options.prompt &&
+        !options.json &&
+        !skip.has(SLOW_FULL_CHECK_COMMAND) &&
+        Boolean(process.stdin.isTTY) &&
+        Boolean(process.stdout.isTTY);
+    if (shouldPrompt) {
+        const runIt = await promptStaleTsIgnoreChoice();
+        if (!runIt)
+            skip.add(SLOW_FULL_CHECK_COMMAND);
+        process.stderr.write('\n');
+    }
+    const showProgress = !options.json && !options.quiet;
+    const report = runFullCheck({
+        dir: resolve(dir),
+        skip: [...skip],
+        ...(showProgress
+            ? {
+                onCommandStart: (command) => process.stderr.write(`Running ${command}...\n`),
+                onProgress: (message) => process.stderr.write(`${message}\n`),
+            }
+            : {}),
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        const text = renderFullCheckReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
         });
         if (text)
             console.log(text);