@bobfrankston/tsfind 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# tsfind
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Find files by name on an NTFS volume, fast. It reads the volume's Master File Table
+([`@bobfrankston/mftwalk`](https://github.com/BobFrankston/mftwalk)) instead of walking, and saves
+the scan, kept current by the drive's change journal, so repeated searches and analyses of the
+same drive take seconds and always see it as it is now. By default it prints
+bare paths, one per line, so the list can be edited (for example, cut down to the files to
+delete). `-count` tallies the matches by name and by extension instead, and `-hogs` shows just the
+largest.
+
+A find-only companion to [tswalk](https://github.com/BobFrankston/tswalk). When the MFT cannot be
+used (off Windows, non-NTFS or network drives, or no admin rights to be had without a UAC prompt),
+tsfind walks the tree instead and says why.
+
+## Install
+
+```bash
+npm install -g @bobfrankston/tsfind
+```
+
+## Usage
+
+```
+tsfind [dir] [pattern] [options]
+```
+
+- **dir** - where to start. If the first argument is not a directory, it is the pattern and the
+  search starts in the current directory.
+- **pattern** - file name: glob (`*` `?`), several separated by `;`, or `/regex/flags`.
+  Case-insensitive; matched against the name only, not the path. Default `*`.
+
+| Flag | Description |
+|------|-------------|
+| `-o file` | Write the list (or the `-count` tables) to a file instead of the console |
+| `-l` | Long: date and size before each path |
+| `-d` | Also report directories and links whose names match (listed with no size) |
+| `-count` | Number and total size of matches by name and by extension |
+| `-sort key` | `-count` order: `size` (default), `count` or `name` |
+| `-top N` | `-count` rows per table (default 50; 0 = all) |
+| `-hogs [name\|ext] [N\|N%]` | Largest totals by name (default) or extension, with each one's share; top N (default 5), or every one taking at least N% |
+| `-q` | No progress or summary |
+| `-help`, `-version` | |
+
+The list is sorted by path. Progress and the summary go to stderr, so stdout carries only the
+list. Links and junctions are never entered.
+
+## The MFT and the saved scan
+
+Reading the MFT needs Windows and NTFS. The whole volume is read whatever
+folder is searched: a 15 TB USB backup drive with 8.7M files takes about 5-8 minutes and 1.6 GB of
+memory. Each read is saved through mftwalk in `%TEMP%\tsfind\mft`, one file per volume, keyed by
+volume serial so it follows the drive to any letter. The drive's NTFS **change journal** keeps it
+current (since 2026-11-07; before that tsfind kept its own snapshot, valid for `-age` minutes):
+
+- **Unchanged** since the save: the saved scan is used as is. Seconds; no admin rights needed.
+- **Changed**: only the MFT records the journal names are read again (admin rights).
+- **No saved scan, or no journal**: the whole MFT is read (admin rights).
+
+### Admin rights (2026-11-09)
+
+When a read needs admin rights and tsfind is not elevated, it elevates by itself **only if Windows
+would allow it without asking**: the account is an administrator and UAC is set not to prompt
+(`ConsentPromptBehaviorAdmin` = 0). A hidden elevated copy of tsfind then brings the saved scan up
+to date, and the search runs on it in your own, unelevated process, so pipes and `-o` work as
+usual. Changes made in the seconds after that update are not included, and the summary says so.
+
+If Windows would ask, tsfind never raises the popup, because it would stall a script. It says why
+on stderr and walks the tree instead (slow on a big drive). Run it elevated for MFT speed.
+
+The walk never enters links or junctions. Entries it cannot read are listed after the summary,
+even with `-q`, since without them the results may be incomplete.
+
+A drive without a change journal is read in full on every run; tsfind prints the command that
+turns one on (`fsutil usn createjournal m=33554432 a=8388608 X:`, elevated). Measured cost of a
+journal on a USB backup drive: creating, renaming and deleting many small files is about 10-30%
+slower; large sequential writes are unaffected. The summary always says where the data came
+from: the saved scan, the MFT, or a walk and why. A saved scan takes about 150-200 bytes per MFT record (S: here,
+2.4M files: 455 MB).
+
+A file with several hard links is found under one of its names only (mftwalk keeps one name per
+MFT record); cargo's `target` directories are the common case.
+
+## Examples
+
+```bash
+tsfind U:\ telemetrydata.db -o tele.txt      # list them to tele.txt for editing
+tsfind U:\ "*telemetry*" -l                  # with dates and sizes
+tsfind U:\ -hogs ext                         # the 5 extensions taking the most space
+tsfind U:\Aged -hogs 2%                      # every name taking at least 2% of U:\Aged
+tsfind U:\ -count -top 30                    # where the space goes, by name and extension
+tsfind "*.bak;*.tmp" -count -sort count      # in the current directory
+```
+
+## License
+
+ISC

package/index.d.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * TSFIND - find files by name on an NTFS volume, fast, from its Master File Table; list them,
+ * count them by name and extension, or show where the space goes
+ *
+ * CHANGE LOG (newest first)
+ * 2026-11-11 — Claude Code (Opus 5.5), at Bob's direction: usage text and README brought into
+ *   line: the same examples in both, and both say a walk lists unreadable entries even with -q.
+ * 2026-11-09 — Claude Code (Opus 5.5), at Bob's direction: "if you can elevate without a prompt
+ *   do so, otherwise fall back", and the fallback is the walk ("bring back the walk"). When the
+ *   saved MFT scan needs an update that needs admin rights, tsfind checks whether Windows would
+ *   elevate without asking (an administrator, UAC set not to prompt: ConsentPromptBehaviorAdmin 0).
+ *   If so, a hidden elevated copy of tsfind (-refreshscan X:) brings the saved scan up to date and
+ *   the search runs on it, here, unelevated, so pipes and -o are unchanged. If Windows would ask,
+ *   tsfind does NOT raise the popup (it would stall scripts): it says why and walks the tree.
+ *   The walk also replaces the old "use tswalk" failures: off Windows, non-NTFS, network paths.
+ *   A stale saved scan is no longer used as is; Bob chose the walk over it.
+ * 2026-11-07 — Claude Code (Opus 5.5), at Bob's direction ("the default should be to use the
+ *   journal"): tsfind's own cache is gone. It now uses mftwalk's saved scans (ScanOptions.cache),
+ *   which the NTFS change journal keeps current: an unchanged volume loads the saved scan without
+ *   elevation, a changed one re-reads only the changed records, a full read happens only with no
+ *   saved scan or no journal. So results are current, not a snapshot up to an hour old, and -age
+ *   and -fresh are gone. tsfind searches the MftVolume directly; its preorder index and zstd cache
+ *   file (TSFINDX1) existed only to be cached, and are removed. If an update needs admin rights
+ *   that are not there, the saved scan is used as it is and the summary says it is not current.
+ * 2026-10-27 (later) — Claude Code (Opus 5.5), at Bob's direction: MFT only, with a cache.
+ *   Bob: "Walking is expensive and is already handled by tswalk... the point of tsfind is to be
+ *   fast. Having a compressed cache that is valid for a limited time allows me to run multiple
+ *   analyses." So the walk, -nomft, -mft and -v are gone. A scan of a volume's MFT is turned into
+ *   tsfind's own index (built only through mftwalk's public accessors) and saved compressed (zstd)
+ *   under the temp directory, one file per volume, keyed by the volume serial number. A cache
+ *   younger than -age minutes (default 60) is used instead of rescanning; -fresh rescans. Because
+ *   reading the cache needs no elevation, only the scan does, later runs work from any prompt.
+ *   When a rescan is not possible (not elevated) but an older cache exists, it is used and its
+ *   age is reported. The start directory goes through realpath, so a path through a junction works.
+ * 2026-10-27 — Claude Code (Opus 5.5), at Bob's direction:
+ *   - The directory is now the first argument: `tsfind dir [pattern]`. If the first argument is not
+ *     a directory it is taken as the pattern and the search starts in the current directory.
+ *     The pattern defaults to * (all files).
+ *   - -hogs [name|ext] [N|N%]: the largest totals by name (default) or by extension; the top N
+ *     (default 5), or with N% every one taking at least N% of the space matched.
+ * 2026-10-14 — Claude Code (Opus 5.5), at Bob's direction: created. A find-only companion to tswalk,
+ * so tswalk is not overloaded. The default output is bare paths, one per line, so the list can be
+ * edited and used for cleanup. -count tallies matches by name and by extension. First use:
+ * telemetrydata.db files on the backup drives.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,791 @@
+#!/usr/bin/env node
+/**
+ * TSFIND - find files by name on an NTFS volume, fast, from its Master File Table; list them,
+ * count them by name and extension, or show where the space goes
+ *
+ * CHANGE LOG (newest first)
+ * 2026-11-11 — Claude Code (Opus 5.5), at Bob's direction: usage text and README brought into
+ *   line: the same examples in both, and both say a walk lists unreadable entries even with -q.
+ * 2026-11-09 — Claude Code (Opus 5.5), at Bob's direction: "if you can elevate without a prompt
+ *   do so, otherwise fall back", and the fallback is the walk ("bring back the walk"). When the
+ *   saved MFT scan needs an update that needs admin rights, tsfind checks whether Windows would
+ *   elevate without asking (an administrator, UAC set not to prompt: ConsentPromptBehaviorAdmin 0).
+ *   If so, a hidden elevated copy of tsfind (-refreshscan X:) brings the saved scan up to date and
+ *   the search runs on it, here, unelevated, so pipes and -o are unchanged. If Windows would ask,
+ *   tsfind does NOT raise the popup (it would stall scripts): it says why and walks the tree.
+ *   The walk also replaces the old "use tswalk" failures: off Windows, non-NTFS, network paths.
+ *   A stale saved scan is no longer used as is; Bob chose the walk over it.
+ * 2026-11-07 — Claude Code (Opus 5.5), at Bob's direction ("the default should be to use the
+ *   journal"): tsfind's own cache is gone. It now uses mftwalk's saved scans (ScanOptions.cache),
+ *   which the NTFS change journal keeps current: an unchanged volume loads the saved scan without
+ *   elevation, a changed one re-reads only the changed records, a full read happens only with no
+ *   saved scan or no journal. So results are current, not a snapshot up to an hour old, and -age
+ *   and -fresh are gone. tsfind searches the MftVolume directly; its preorder index and zstd cache
+ *   file (TSFINDX1) existed only to be cached, and are removed. If an update needs admin rights
+ *   that are not there, the saved scan is used as it is and the summary says it is not current.
+ * 2026-10-27 (later) — Claude Code (Opus 5.5), at Bob's direction: MFT only, with a cache.
+ *   Bob: "Walking is expensive and is already handled by tswalk... the point of tsfind is to be
+ *   fast. Having a compressed cache that is valid for a limited time allows me to run multiple
+ *   analyses." So the walk, -nomft, -mft and -v are gone. A scan of a volume's MFT is turned into
+ *   tsfind's own index (built only through mftwalk's public accessors) and saved compressed (zstd)
+ *   under the temp directory, one file per volume, keyed by the volume serial number. A cache
+ *   younger than -age minutes (default 60) is used instead of rescanning; -fresh rescans. Because
+ *   reading the cache needs no elevation, only the scan does, later runs work from any prompt.
+ *   When a rescan is not possible (not elevated) but an older cache exists, it is used and its
+ *   age is reported. The start directory goes through realpath, so a path through a junction works.
+ * 2026-10-27 — Claude Code (Opus 5.5), at Bob's direction:
+ *   - The directory is now the first argument: `tsfind dir [pattern]`. If the first argument is not
+ *     a directory it is taken as the pattern and the search starts in the current directory.
+ *     The pattern defaults to * (all files).
+ *   - -hogs [name|ext] [N|N%]: the largest totals by name (default) or by extension; the top N
+ *     (default 5), or with N% every one taking at least N% of the space matched.
+ * 2026-10-14 — Claude Code (Opus 5.5), at Bob's direction: created. A find-only companion to tswalk,
+ * so tswalk is not overloaded. The default output is bare paths, one per line, so the list can be
+ * edited and used for cleanup. -count tallies matches by name and by extension. First use:
+ * telemetrydata.db files on the backup drives.
+ */
+import * as fp from 'node:fs/promises';
+import * as os from 'node:os';
+import { getDriveInfo } from '@bobfrankston/dirutil';
+import * as path from 'node:path';
+import { styleText } from 'node:util';
+import { finished } from 'node:stream/promises';
+import { spawn, spawnSync } from 'node:child_process';
+import packageJson from './package.json' with { type: 'json' };
+const version = packageJson.version;
+/** Default rows per -count table */
+const DEFAULT_TOP = 50;
+/** Default rows for -hogs */
+const DEFAULT_HOGS = 5;
+/** Lines handed to the output stream per write */
+const WRITE_BATCH = 10000;
+const CLEAR_LINE = '\x1b[2K\r';
+/**
+ * Change journal size suggested when a drive has none (Windows' usual 32 MB, 8 MB steps); it only
+ * has to hold the changes between two runs. Same suggestion as tswalk's.
+ */
+const SUGGESTED_JOURNAL = 'm=33554432 a=8388608';
+/** Directories read at once by the walk */
+const WALK_CONCURRENCY = 16;
+/** Unreadable directories named in the walk's summary; the rest are only counted */
+const WALK_ERRORS_SHOWN = 5;
+/** Well-known SIDs in `whoami /groups` */
+const Sids = {
+    Administrators: 'S-1-5-32-544', /** BUILTIN\Administrators (deny-only in an unelevated admin token) */
+    HighIntegrity: 'S-1-16-12288', /** High Mandatory Level: the process is elevated */
+};
+/** HKLM key holding the UAC settings */
+const UAC_KEY = 'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System';
+/** ConsentPromptBehaviorAdmin value meaning "elevate administrators without prompting" */
+const UAC_ELEVATE_WITHOUT_PROMPT = 0;
+function usage() {
+    return `tsfind v${version} - find files by name on an NTFS volume, fast, from its Master File Table
+
+Usage: tsfind [dir] [pattern] [options]
+    dir         Where to start. If the first argument is not a directory, it is the pattern
+                and the search starts in the current directory.
+    pattern     File name to find: glob (* ?), several separated by ;, or /regex/flags.
+                Case-insensitive; matched against the name only, not the path. Default: *
+
+Options:
+    -o file     Write the list (or the tables) to file instead of the console
+    -l          Long: date and size before each path (default: path only, one per line,
+                so the list can be edited)
+    -d          Also report directories and links whose names match (listed with no size;
+                the search never goes inside links or junctions)
+    -count      Instead of listing: number and total size of matches by name and by
+                extension
+    -sort key   -count order: size (default), count or name
+    -top N      -count rows per table (default ${DEFAULT_TOP}; 0 = all)
+    -hogs [name|ext] [N|N%]
+                Instead of listing: where the space goes. The largest totals by name
+                (default) or by extension, with each one's share of the space matched.
+                N = how many (default ${DEFAULT_HOGS}); N% = every one taking at least N%.
+    -q          No progress or summary
+    -h, -help   This message
+    -version    Version
+
+How it works: tsfind reads the volume's NTFS Master File Table (Windows, NTFS) rather than walking:
+minutes instead of the hours a walk can take on a big drive. Each read is saved, one file per
+volume, in ${cacheDir()}, and the drive's change journal keeps it current:
+  - unchanged since the save: the saved scan is used as is (seconds; no admin rights needed)
+  - changed: only the changed MFT records are read again (admin rights)
+  - no saved scan yet, or no change journal: the whole MFT is read (admin rights)
+So every search sees the drive as it is now. A drive without a change journal is read in full
+every time; tsfind prints the fsutil command that turns one on.
+
+Admin rights: when a read needs them and tsfind is not elevated, it elevates by itself only if
+Windows would allow it without asking (you are an administrator and UAC is set not to prompt).
+Otherwise it never raises a UAC popup, which would stall a script: it says why on stderr and
+walks the tree instead (slow on a big drive). It also walks off Windows, on non-NTFS drives and
+on network paths. The summary always says which it did. Entries a walk cannot read are listed
+after the summary, even with -q, since the results may then be incomplete.
+
+Progress and the summary go to stderr, so stdout carries only the list.
+
+Examples:
+    tsfind U:\\ telemetrydata.db -o tele.txt     List them to tele.txt for editing
+    tsfind U:\\ "*telemetry*" -l                With dates and sizes
+    tsfind U:\\ -hogs ext                       The 5 extensions taking the most space
+    tsfind U:\\Aged -hogs 2%                    Every name taking at least 2% of U:\\Aged
+    tsfind U:\\ -count -top 30                  Where the space goes, by name and extension
+    tsfind "*.bak;*.tmp" -count -sort count     In the current directory
+`;
+}
+function fail(message) {
+    console.error(styleText(['red'], message));
+    console.error('tsfind -help for usage');
+    process.exit(1);
+}
+function parseArgs(args) {
+    if (args.length === 0) {
+        console.log(usage());
+        process.exit(1);
+    }
+    const options = {
+        positional: [], patterns: null, top: '.', outFile: '', long: false, dirs: false, count: false,
+        sort: 'size', rows: DEFAULT_TOP, hogs: null, hogsRows: DEFAULT_HOGS, hogsPercent: 0, quiet: false,
+        refreshScan: '',
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith('-') || arg === '-') {
+            options.positional.push(arg);
+            continue;
+        }
+        const needValue = () => {
+            if (i + 1 >= args.length)
+                fail(`${arg} needs a value`);
+            return args[++i];
+        };
+        switch (arg.replace(/^--/, '-').toLowerCase()) {
+            case '-o':
+                options.outFile = needValue();
+                break;
+            case '-l':
+                options.long = true;
+                break;
+            case '-d':
+                options.dirs = true;
+                break;
+            case '-count':
+                options.count = true;
+                break;
+            case '-sort': {
+                const key = needValue().toLowerCase();
+                if (key !== 'size' && key !== 'count' && key !== 'name')
+                    fail(`-sort must be size, count or name, not ${key}`);
+                options.sort = key;
+                break;
+            }
+            case '-top': {
+                const n = needValue();
+                if (!/^\d+$/.test(n))
+                    fail(`-top needs a number, not ${n}`);
+                options.rows = parseInt(n);
+                break;
+            }
+            case '-hogs': {
+                options.hogs = 'name';
+                // Both qualifiers are optional and may come in either order: -hogs ext 10, -hogs 3% name.
+                for (let taken = 0; taken < 2 && i + 1 < args.length; taken++) {
+                    const next = args[i + 1].toLowerCase();
+                    const amount = /^(\d+(?:\.\d+)?)(%?)$/.exec(next);
+                    if (next === 'name' || next === 'ext' || next === 'extension') {
+                        options.hogs = next === 'name' ? 'name' : 'ext';
+                    }
+                    else if (amount && amount[2]) {
+                        options.hogsPercent = parseFloat(amount[1]);
+                        if (options.hogsPercent <= 0 || options.hogsPercent > 100)
+                            fail(`-hogs ${next}: the percentage must be above 0 and at most 100`);
+                    }
+                    else if (amount) {
+                        if (!/^\d+$/.test(next) || parseInt(next) === 0)
+                            fail(`-hogs ${next}: the count must be a whole number above 0`);
+                        options.hogsRows = parseInt(next);
+                    }
+                    else {
+                        break;
+                    }
+                    i++;
+                }
+                break;
+            }
+            // 2026-11-07: retired with tsfind's own cache; said explicitly rather than "Unknown option".
+            case '-age':
+            case '-fresh':
+                fail(`${arg} is gone: the drive's change journal now keeps the saved scan current, so every search is up to date.`);
+            case '-q':
+                options.quiet = true;
+                break;
+            case '-refreshscan': {
+                const drive = needValue();
+                if (!/^[A-Za-z]:$/.test(drive))
+                    fail(`-refreshscan needs a drive like C:, not ${drive}`);
+                options.refreshScan = drive.toUpperCase();
+                break;
+            }
+            case '-h':
+            case '-help':
+                console.log(usage());
+                process.exit(0);
+            case '-version':
+                console.log(`tsfind v${version}`);
+                process.exit(0);
+            default:
+                fail(`Unknown option: ${arg}`);
+        }
+    }
+    if (options.positional.length > 2)
+        fail(`Too many arguments: ${options.positional.join(' ')} (dir, then pattern)`);
+    if (options.hogs && options.count)
+        fail('Use -count or -hogs, not both');
+    return options;
+}
+/** A /body/flags pattern, which is a regex rather than a glob */
+function isRegexPattern(p) {
+    return p.startsWith('/') && p.lastIndexOf('/') > 0;
+}
+/**
+ * Sort out [dir] [pattern]: the first argument is the directory if it is one; otherwise it is the
+ * pattern and the search starts in the current directory. Something that looks like a path but
+ * is not a directory is reported, rather than searched for as a file name it could never match.
+ */
+async function resolvePositional(options) {
+    const [first, second] = options.positional;
+    let pattern = '*';
+    if (first !== undefined) {
+        let isDir = false;
+        let statError = '';
+        try {
+            isDir = (await fp.stat(first)).isDirectory();
+        }
+        catch (error) {
+            // Not lost: "no such directory" is the ordinary sign that first is a pattern; if first
+            // looks like a path instead, the code is reported by the fail just below.
+            statError = error.code ?? error.message;
+        }
+        const looksLikePath = !isRegexPattern(first) && /[\\/:]/.test(first);
+        if (isDir) {
+            options.top = first;
+            if (second !== undefined)
+                pattern = second;
+        }
+        else if (looksLikePath) {
+            fail(statError ? `Cannot search ${first}: ${statError}` : `Not a directory: ${first}`);
+        }
+        else if (second !== undefined) {
+            fail(`${first} is not a directory; the directory comes first: tsfind dir [pattern]`);
+        }
+        else {
+            pattern = first;
+        }
+    }
+    options.patterns = pattern.split(';').filter(Boolean);
+    if (options.patterns.length === 0)
+        fail('Empty pattern');
+}
+/**
+ * Name patterns to RegExps: /body/flags is a regex; anything else is a glob, anchored and
+ * case-insensitive, in which only * and ? are special.
+ */
+function compilePatterns(patterns) {
+    return patterns.map(p => {
+        const last = p.lastIndexOf('/');
+        if (isRegexPattern(p)) {
+            try {
+                return new RegExp(p.slice(1, last), p.slice(last + 1));
+            }
+            catch (error) {
+                fail(`Bad regex ${p}: ${error.message}`);
+            }
+        }
+        const body = p.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.');
+        return new RegExp('^' + body + '$', 'i');
+    });
+}
+let progressAt = 0;
+function progress(options, text) {
+    if (options.quiet || !process.stderr.isTTY)
+        return;
+    const now = Date.now();
+    if (now - progressAt < 1000)
+        return;
+    progressAt = now;
+    process.stderr.write(CLEAR_LINE + text);
+}
+function clearProgress(options) {
+    if (!options.quiet && process.stderr.isTTY)
+        process.stderr.write(CLEAR_LINE);
+}
+// ── Volume: mftwalk's saved scan, kept current by the change journal ──
+function cacheDir() {
+    return path.join(os.tmpdir(), 'tsfind', 'mft');
+}
+/** One line saying where the volume's data came from, for the summary */
+function sourceText(volume) {
+    const origin = volume.origin;
+    switch (origin.source) {
+        case 'cache':
+            return origin.changed
+                ? `saved MFT scan, NOT current: ${origin.reason}`
+                : `saved MFT scan: ${origin.reason}`;
+        case 'updated':
+            return origin.reason;
+    }
+    return `MFT read in full: ${origin.reason}`;
+}
+/** A walk, with the reason it is not the MFT, said now on stderr and again in the summary */
+function walkSource(top, reason, options) {
+    if (!options.quiet)
+        console.error(styleText(['red'], `Walking ${top} instead of reading the MFT: ${reason}`));
+    return { volume: null, text: `directory walk, not the MFT: ${reason}`, stale: false };
+}
+/**
+ * Can this process get admin rights without anyone being asked? True only for an administrator
+ * (deny-only Administrators in this unelevated token) on a machine whose UAC elevates
+ * administrators without prompting. `why` says what stands in the way when it is false.
+ */
+function silentElevation() {
+    const groups = spawnSync('whoami', ['/groups', '/fo', 'csv', '/nh'], { encoding: 'utf8' });
+    if (groups.status !== 0) {
+        return { possible: false, why: `cannot tell whether elevation would prompt (whoami: ${groups.error?.message ?? groups.stderr.trim()})` };
+    }
+    if (groups.stdout.includes(Sids.HighIntegrity)) {
+        return { possible: false, why: 'Windows refused the MFT even though tsfind is already elevated' };
+    }
+    if (!groups.stdout.includes(Sids.Administrators)) {
+        return { possible: false, why: 'it needs admin rights, and this account is not an administrator' };
+    }
+    const uac = spawnSync('reg', ['query', UAC_KEY, '/v', 'ConsentPromptBehaviorAdmin'], { encoding: 'utf8' });
+    const value = /ConsentPromptBehaviorAdmin\s+REG_DWORD\s+0x([0-9a-f]+)/i.exec(uac.stdout ?? '');
+    if (!value) {
+        return { possible: false, why: `it needs admin rights, and the UAC setting cannot be read (${uac.error?.message ?? (uac.stderr.trim() || 'no ConsentPromptBehaviorAdmin')}), so elevating might raise a prompt` };
+    }
+    const behavior = parseInt(value[1], 16);
+    if (behavior !== UAC_ELEVATE_WITHOUT_PROMPT) {
+        return { possible: false, why: `it needs admin rights, and UAC here would ask (ConsentPromptBehaviorAdmin ${behavior}); tsfind will not raise a popup that stalls a script. Run tsfind elevated for MFT speed` };
+    }
+    return { possible: true, why: '' };
+}
+/** Where the hidden elevated copy leaves its result, since it has no console the caller can see */
+function refreshResultFile(driveName) {
+    return path.join(os.tmpdir(), 'tsfind', `refresh-${driveName[0]}.txt`);
+}
+/**
+ * Bring driveName's saved MFT scan up to date from a hidden, elevated copy of tsfind
+ * (-refreshscan). Only called when silentElevation() says Windows will not ask; the "runas" verb
+ * is Windows' own elevation request. Returns '' on success, else why it failed.
+ */
+async function refreshElevated(driveName, options) {
+    const resultFile = refreshResultFile(driveName);
+    await fp.mkdir(path.dirname(resultFile), { recursive: true });
+    await fp.rm(resultFile, { force: true });
+    const psQuote = (s) => `'${s.replace(/'/g, "''")}'`;
+    const childArgs = `"${import.meta.filename}" -refreshscan ${driveName}`;
+    const command = `$p = Start-Process -FilePath ${psQuote(process.execPath)} -ArgumentList ${psQuote(childArgs)} ` +
+        `-Verb RunAs -WindowStyle Hidden -Wait -PassThru; exit $p.ExitCode`;
+    const started = Date.now();
+    const ticker = setInterval(() => progress(options, `Updating ${driveName}'s saved MFT scan, elevated: ${elapsedText(Date.now() - started)}`), 1000);
+    const { code, stderr } = await new Promise(resolve => {
+        const child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command], { stdio: ['ignore', 'ignore', 'pipe'] });
+        let errText = '';
+        child.stderr.on('data', chunk => errText += chunk);
+        child.on('error', error => resolve({ code: -1, stderr: error.message }));
+        child.on('close', exitCode => resolve({ code: exitCode, stderr: errText }));
+    });
+    clearInterval(ticker);
+    clearProgress(options);
+    let result = '';
+    try {
+        result = (await fp.readFile(resultFile, 'utf8')).trim();
+    }
+    catch (error) {
+        // Not lost: no result file means the elevated copy never ran or died early; the failure
+        // below then reports PowerShell's own error and the exit code instead.
+        result = '';
+    }
+    if (code === 0 && result === 'ok')
+        return '';
+    return result || stderr.trim().split('\n')[0] || `the elevated copy of tsfind exited with code ${code}`;
+}
+/**
+ * -refreshscan X: the hidden elevated copy. Brings X:'s saved scan up to date (mftwalk: updated
+ * from the journal, or read in full) and leaves 'ok' or the error in refreshResultFile.
+ */
+async function refreshScanAndExit(driveName) {
+    const resultFile = refreshResultFile(driveName);
+    let result = 'ok';
+    try {
+        const { scanVolume } = await import('@bobfrankston/mftwalk');
+        await scanVolume(driveName + '\\', { cache: { dir: cacheDir() } });
+    }
+    catch (error) {
+        result = error.message ?? String(error);
+    }
+    await fp.mkdir(path.dirname(resultFile), { recursive: true });
+    await fp.writeFile(resultFile, result);
+    process.exit(result === 'ok' ? 0 : 1);
+}
+/**
+ * Where to search `top`: the volume from mftwalk's saved scan (see usage: unchanged -> saved scan,
+ * changed -> updated from the journal, else a full read). When that needs admin rights tsfind does
+ * not have, it elevates only if Windows will not ask; otherwise, and whenever the MFT cannot be
+ * used at all, it walks the tree and says why.
+ */
+async function getSource(top, options) {
+    if (process.platform !== 'win32')
+        return walkSource(top, 'the MFT is read on Windows only', options);
+    if (!/^[A-Za-z]:\\/.test(top))
+        return walkSource(top, 'not on a drive letter (a network path?)', options);
+    const drive = getDriveInfo(top.slice(0, 3));
+    if (drive.fileSystem !== 'NTFS')
+        return walkSource(top, `${top.slice(0, 2)} is ${drive.fileSystem || 'not a local file system'}, not NTFS`, options);
+    const driveName = top.slice(0, 2).toUpperCase();
+    const label = drive.volumeName ? `"${drive.volumeName}"` : '(no label)';
+    if (!options.quiet)
+        console.error(styleText(['blue'], `Reading ${driveName} ${label}: saved MFT scan if current, else from the MFT`));
+    const { scanVolume, MftError } = await import('@bobfrankston/mftwalk');
+    const scanOptions = {
+        onProgress: (done, total) => progress(options, `MFT ${done.toLocaleString()} / ${total.toLocaleString()} records`),
+        cache: { dir: cacheDir() },
+        log: msg => { if (!options.quiet)
+            console.error(styleText(['red'], msg)); },
+    };
+    try {
+        const volume = await scanVolume(top, scanOptions);
+        clearProgress(options);
+        return { volume, text: sourceText(volume), stale: volume.origin.changed };
+    }
+    catch (error) {
+        clearProgress(options);
+        if (!(error instanceof MftError))
+            throw error;
+        // Not swallowed: the reason goes to stderr and into the summary, and the walk takes over.
+        if (error.code !== 'EPERM')
+            return walkSource(top, `cannot read the MFT of ${driveName}: ${error.message}`, options);
+    }
+    const elevation = silentElevation();
+    if (!elevation.possible)
+        return walkSource(top, elevation.why, options);
+    if (!options.quiet)
+        console.error(styleText(['blue'], `Updating ${driveName}'s saved MFT scan elevated (UAC here elevates administrators without asking)`));
+    const refreshError = await refreshElevated(driveName, options);
+    if (refreshError)
+        return walkSource(top, `the elevated update of ${driveName}'s saved scan failed: ${refreshError}`, options);
+    const updatedAt = new Date();
+    try {
+        // trust: the saved scan was brought up to date a moment ago; changes since then (a busy
+        // C: always has some) would need admin rights again, so they are named, not read.
+        const volume = await scanVolume(top, { ...scanOptions, cache: { dir: cacheDir(), trust: true } });
+        clearProgress(options);
+        const text = volume.origin.changed
+            ? `saved MFT scan, brought up to date elevated at ${updatedAt.toLocaleTimeString()} (changes after that are not included)`
+            : sourceText(volume);
+        return { volume, text, stale: false };
+    }
+    catch (error) {
+        clearProgress(options);
+        if (!(error instanceof MftError))
+            throw error;
+        return walkSource(top, `cannot load ${driveName}'s saved scan after updating it: ${error.message}`, options);
+    }
+}
+// ── Walk: the classic way, when the MFT cannot be used ────────────
+/** Run at most `max` jobs at once; the rest wait their turn */
+function makeLimiter(max) {
+    let running = 0;
+    const waiting = [];
+    return async (job) => {
+        if (running >= max)
+            await new Promise(resolve => waiting.push(resolve));
+        else
+            running++;
+        try {
+            return await job();
+        }
+        finally {
+            // Hand the slot straight to the next waiter, or give it back.
+            const next = waiting.shift();
+            if (next)
+                next();
+            else
+                running--;
+        }
+    };
+}
+/**
+ * Hand each match beneath `top` to onFound, reading WALK_CONCURRENCY directories at a time.
+ * Links and junctions are reported like directories but never entered, as in searchVolume.
+ * Returns the directories read and those that could not be (or matches that could not be stat'd).
+ */
+async function walkTree(top, regexes, options, onFound) {
+    const limit = makeLimiter(WALK_CONCURRENCY);
+    const errors = [];
+    let dirs = 0;
+    const visit = async (dir) => {
+        let entries;
+        try {
+            entries = await limit(() => fp.readdir(dir, { withFileTypes: true }));
+        }
+        catch (error) {
+            // Not lost: listed in the summary (count, and the first few by name).
+            errors.push(`${dir}: ${error.code ?? error.message}`);
+            return;
+        }
+        dirs++;
+        progress(options, `Walked ${dirs.toLocaleString()} directories`);
+        const subdirs = [];
+        const stats = [];
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            const isLink = entry.isSymbolicLink();
+            const isDir = entry.isDirectory() || isLink;
+            if (isDir && !isLink)
+                subdirs.push(full);
+            if (!regexes.some(rx => rx.test(entry.name)))
+                continue;
+            if (isDir && !options.dirs)
+                continue;
+            stats.push(limit(() => fp.lstat(full)).then(st => onFound({ path: full, name: entry.name, size: isDir ? 0 : st.size, mtime: st.mtime, isDir }), 
+            // Not lost: a match that vanished or cannot be read is listed with the summary.
+            (error) => { errors.push(`${full}: ${error.code ?? error.message}`); }));
+        }
+        await Promise.all([...stats, ...subdirs.map(visit)]);
+    };
+    await visit(top);
+    clearProgress(options);
+    return { dirs, errors };
+}
+/**
+ * Hand each match beneath `start` to onFound; returns the number of directories searched.
+ * Depth-first through mftwalk's accessors. Links have no children in the volume, so their
+ * contents are never searched; NTFS's own files ($MFT, $Extend ...) are skipped, as readdir does.
+ */
+function searchVolume(volume, start, regexes, options, onFound) {
+    let dirs = 1;
+    const stack = [start];
+    while (stack.length) {
+        const kids = volume.children(stack.pop());
+        for (let k = kids.length - 1; k >= 0; k--) {
+            const id = kids[k];
+            if (volume.isMetafile(id))
+                continue;
+            const isLink = volume.isLink(id);
+            const isDir = volume.isDirectory(id) || isLink;
+            if (isDir && !isLink) {
+                dirs++;
+                stack.push(id);
+            }
+            const name = volume.name(id);
+            if (!regexes.some(rx => rx.test(name)))
+                continue;
+            if (isDir && !options.dirs)
+                continue;
+            onFound({ path: volume.path(id), name, size: isDir ? 0 : volume.size(id), mtime: volume.mtime(id), isDir });
+        }
+    }
+    return dirs;
+}
+// ── Output ─────────────────────────────────────────────────────────
+/** Write lines to the stream in batches, waiting for it to drain */
+async function writeLines(out, lines) {
+    for (let i = 0; i < lines.length; i += WRITE_BATCH) {
+        const chunk = lines.slice(i, i + WRITE_BATCH).join('\n') + '\n';
+        if (!out.write(chunk))
+            await new Promise(resolve => out.once('drain', () => resolve()));
+    }
+}
+function formatBytes(bytes) {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return unit === 0 ? `${value} B` : `${value.toFixed(value < 10 ? 2 : 1)} ${units[unit]}`;
+}
+function formatDate(date) {
+    if (!date)
+        return ' '.repeat(16);
+    const local = new Date(date.getTime() - date.getTimezoneOffset() * 60000);
+    return local.toISOString().slice(0, 16).replace('T', ' ');
+}
+function elapsedText(ms) {
+    const totalSec = Math.round(ms / 1000);
+    const hours = Math.floor(totalSec / 3600);
+    const mins = Math.floor(totalSec / 60) % 60;
+    if (hours > 0)
+        return `${hours}h ${mins}m`;
+    return mins > 0 ? `${mins}m ${totalSec % 60}s` : `${(ms / 1000).toFixed(1)}s`;
+}
+function addTally(table, label, size) {
+    const key = label.toLowerCase();
+    const tally = table.get(key);
+    if (tally) {
+        tally.count++;
+        tally.bytes += size;
+    }
+    else {
+        table.set(key, { label, count: 1, bytes: size });
+    }
+}
+function tallyLines(title, table, options) {
+    const rows = Array.from(table.values());
+    switch (options.sort) {
+        case 'size':
+            rows.sort((a, b) => b.bytes - a.bytes || b.count - a.count);
+            break;
+        case 'count':
+            rows.sort((a, b) => b.count - a.count || b.bytes - a.bytes);
+            break;
+        case 'name':
+            rows.sort((a, b) => a.label.localeCompare(b.label, undefined, { sensitivity: 'base' }));
+            break;
+    }
+    const shown = options.rows > 0 ? rows.slice(0, options.rows) : rows;
+    const heading = shown.length < rows.length
+        ? `${title}: top ${shown.length} of ${rows.length.toLocaleString()}, by ${options.sort}`
+        : `${title}: ${rows.length.toLocaleString()}, by ${options.sort}`;
+    return [
+        heading,
+        `${'Count'.padStart(12)} ${'Size'.padStart(10)}  ${title}`,
+        ...shown.map(t => `${t.count.toLocaleString().padStart(12)} ${formatBytes(t.bytes).padStart(10)}  ${t.label}`),
+        '',
+    ];
+}
+/**
+ * -hogs: the largest totals, by size, with each one's share of all the space matched. Either the
+ * top hogsRows, or with hogsPercent every row whose share is at least that.
+ */
+function hogsLines(table, totalBytes, options) {
+    const title = options.hogs === 'name' ? 'Name' : 'Extension';
+    const rows = Array.from(table.values()).sort((a, b) => b.bytes - a.bytes || b.count - a.count);
+    const share = (t) => totalBytes > 0 ? t.bytes / totalBytes * 100 : 0;
+    const shown = options.hogsPercent > 0
+        ? rows.filter(t => share(t) >= options.hogsPercent)
+        : rows.slice(0, options.hogsRows);
+    const shownBytes = shown.reduce((sum, t) => sum + t.bytes, 0);
+    const which = options.hogsPercent > 0 ? `at least ${options.hogsPercent}% each` : `top ${shown.length}`;
+    return [
+        `Largest by ${title.toLowerCase()}: ${which}, of ${rows.length.toLocaleString()}; ` +
+            `together ${formatBytes(shownBytes)} of ${formatBytes(totalBytes)} (${(totalBytes > 0 ? shownBytes / totalBytes * 100 : 0).toFixed(1)}%)`,
+        `${'Count'.padStart(12)} ${'Size'.padStart(10)} ${'Share'.padStart(6)}  ${title}`,
+        ...shown.map(t => `${t.count.toLocaleString().padStart(12)} ${formatBytes(t.bytes).padStart(10)} ${(share(t).toFixed(1) + '%').padStart(6)}  ${t.label}`),
+        ...(shown.length === 0 && rows.length > 0 ? [`(none; the largest, ${rows[0].label}, takes ${share(rows[0]).toFixed(1)}%)`] : []),
+        '',
+    ];
+}
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.refreshScan)
+        await refreshScanAndExit(options.refreshScan);
+    await resolvePositional(options);
+    const regexes = compilePatterns(options.patterns);
+    let top;
+    try {
+        // realpath goes through junctions, so the folder is found where it really is in the MFT.
+        top = await fp.realpath(path.resolve(options.top));
+        if (!(await fp.stat(top)).isDirectory())
+            fail(`Not a directory: ${top}`);
+    }
+    catch (error) {
+        fail(`Cannot search ${options.top}: ${error.code ?? error.message}`);
+    }
+    // Open -o's file before searching, so a bad path fails now rather than after a long scan.
+    let outHandle;
+    if (options.outFile) {
+        try {
+            outHandle = await fp.open(options.outFile, 'w');
+        }
+        catch (error) {
+            fail(`Cannot write ${options.outFile}: ${error.code ?? error.message}`);
+        }
+    }
+    // A closed pipe (e.g. | head) just ends the output.
+    process.stdout.on('error', (error) => {
+        if (error.code === 'EPIPE')
+            process.exit(0);
+        throw error;
+    });
+    const start = Date.now();
+    let source = await getSource(top, options);
+    const entry = source.volume ? source.volume.lookup(top) : -1;
+    if (source.volume && entry < 0)
+        source = walkSource(top, `${top} is not in the MFT data (${source.text})`, options);
+    const found = [];
+    const byName = new Map();
+    const byExt = new Map();
+    let matchCount = 0;
+    let matchBytes = 0;
+    const tallying = options.count || !!options.hogs;
+    const onFound = (f) => {
+        matchCount++;
+        matchBytes += f.size;
+        if (!tallying) {
+            found.push(f);
+            return;
+        }
+        addTally(byName, f.name, f.size);
+        addTally(byExt, f.isDir ? '(directory)' : path.extname(f.name) || '(none)', f.size);
+    };
+    let dirs;
+    let walkErrors = [];
+    if (source.volume) {
+        dirs = searchVolume(source.volume, entry, regexes, options, onFound);
+    }
+    else {
+        ({ dirs, errors: walkErrors } = await walkTree(top, regexes, options, onFound));
+    }
+    const elapsed = Date.now() - start;
+    let lines;
+    if (options.hogs) {
+        lines = hogsLines(options.hogs === 'name' ? byName : byExt, matchBytes, options);
+    }
+    else if (options.count) {
+        lines = [...tallyLines('Name', byName, options), ...tallyLines('Extension', byExt, options)];
+    }
+    else {
+        const keyed = found.map(f => ({ key: f.path.toLowerCase(), f }));
+        keyed.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+        lines = options.long
+            ? keyed.map(({ f }) => `${formatDate(f.mtime)} ${(f.isDir ? '<DIR>' : f.size.toLocaleString()).padStart(15)}  ${f.path}`)
+            : keyed.map(({ f }) => f.path);
+    }
+    const out = outHandle ? outHandle.createWriteStream({ encoding: 'utf8' }) : process.stdout;
+    await writeLines(out, lines);
+    if (outHandle) {
+        out.end();
+        await finished(out);
+    }
+    if (!options.quiet) {
+        const what = options.dirs ? 'matches' : 'files';
+        console.error(`${matchCount.toLocaleString()} ${what}, ${formatBytes(matchBytes)}; ${dirs.toLocaleString()} directories searched; ` +
+            `${elapsedText(elapsed)}${options.outFile ? `; written to ${path.resolve(options.outFile)}` : ''}`);
+        console.error(styleText([source.stale ? 'red' : 'blue'], `From the ${source.text}.`));
+    }
+    else if (source.stale) {
+        console.error(styleText(['red'], `From the ${source.text}.`));
+    }
+    // Shown even with -q: an incomplete walk is a wrong answer unless it says so.
+    if (walkErrors.length) {
+        console.error(styleText(['red'], `${walkErrors.length.toLocaleString()} could not be read, so the results may be incomplete:`));
+        for (const line of walkErrors.slice(0, WALK_ERRORS_SHOWN))
+            console.error(styleText(['red'], `  ${line}`));
+        if (walkErrors.length > WALK_ERRORS_SHOWN)
+            console.error(styleText(['red'], `  ... and ${(walkErrors.length - WALK_ERRORS_SHOWN).toLocaleString()} more`));
+    }
+    // 2026-11-07: as in tswalk, a drive without a change journal is worth a visible warning,
+    // since every run on it pays for a full MFT read.
+    const volume = source.volume;
+    if (volume && volume.origin.source === 'disk' && !volume.origin.journal && !options.quiet) {
+        const driveName = top.slice(0, 2).toUpperCase();
+        console.error(styleText(['red'], `NOTE: ${driveName} has no change journal, so the saved scan cannot be checked and EVERY run reads the whole MFT.\n` +
+            `  Fix, once, elevated: fsutil usn createjournal ${SUGGESTED_JOURNAL} ${driveName}`));
+    }
+}
+if (import.meta.main) {
+    await main();
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@bobfrankston/tsfind",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Find files by name in a directory tree; list them for editing, or count them by name and extension. Optional NTFS MFT reading for big drives.",
+  "main": "index.js",
+  "bin": {
+    "tsfind": "./index.js"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "find",
+    "file-search",
+    "directory",
+    "ntfs",
+    "mft",
+    "disk-usage"
+  ],
+  "author": "Bob Frankston",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:BobFrankston/tsfind.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BobFrankston/tsfind/issues"
+  },
+  "homepage": "https://github.com/BobFrankston/tsfind#readme",
+  "dependencies": {
+    "@bobfrankston/dirutil": "^1.6.5",
+    "@bobfrankston/mftwalk": "^0.1.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "allowScripts": {
+    "file:../../../../projects/NodeJS/dirutil": true,
+    "koffi": true
+  },
+  ".dependencies": {
+    "@bobfrankston/dirutil": "file:../../projects/NodeJS/dirutil",
+    "@bobfrankston/mftwalk": "file:../mftwalk"
+  },
+  ".transformedSnapshot": {
+    "dependencies": {
+      "@bobfrankston/dirutil": "^1.6.5",
+      "@bobfrankston/mftwalk": "^0.1.4"
+    }
+  }
+}