@bobfrankston/tsfind 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,78 @@
-# 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 caches
+the scan, so repeated searches and analyses of the same drive take seconds. 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), which walks trees
+(non-NTFS and network drives included).
+
+## 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% |
+| `-age N` | Use a cached scan up to N minutes old (default 60) |
+| `-fresh` | Rescan the MFT even if a cached scan is young enough |
+| `-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 cache
+
+Scanning the MFT needs Windows, NTFS and an elevated prompt (e.g. `gsudo`); tsfind does not walk.
+The whole volume is scanned 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 scan is saved, zstd-compressed, as `%TEMP%\tsfind\<volume label>-<volume serial>.idx.zst` (e.g. `20251211y-F860296A.idx.zst`): about 11 bytes
+per entry (Y: here: 1.33M entries, 14 MB), so about 110 MB for 10M files. A cache younger than
+`-age` minutes (default 60) is used instead of rescanning, for any folder on that volume, and
+reading it needs no elevation. It is a snapshot: changes since the scan are not seen until it
+expires or `-fresh` is given. When a rescan is not possible (not elevated), an older cache is used
+and the summary says how old. Each drive has its own cache, named by volume label (readable) and
+volume serial number (unique), so it follows the drive to whatever letter it is mounted under, and
+two drives with the same label are kept apart. Renaming a drive's label means one rescan.
+
+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
+gsudo tsfind U:\ -hogs ext                   # scans the MFT; the 5 extensions taking the most space
+tsfind U:\ -hogs 2%                          # from the cache: every name taking at least 2%
+tsfind U:\Aged -count -top 30                # from the cache: by name and extension
+tsfind U:\ telemetrydata.db -o tele.txt      # list for editing
+tsfind U:\ "*telemetry*" -l                  # with dates and sizes
+gsudo tsfind U:\ -fresh -hogs                # rescan now
+```
+
+## License
+
+ISC

package/index.d.ts

@@ -0,0 +1,29 @@
+#!/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-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,742 @@
+#!/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-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 { createReadStream, createWriteStream } from 'node:fs';
+import * as os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { styleText } from 'node:util';
+import { Readable } from 'node:stream';
+import { finished, pipeline } from 'node:stream/promises';
+import { createZstdCompress, createZstdDecompress } from 'node:zlib';
+import packageJson from './package.json' with { type: 'json' };
+const version = packageJson.version;
+/** A cache younger than this many minutes is used instead of rescanning (-age changes it) */
+const DEFAULT_CACHE_MINUTES = 60;
+/** 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;
+/** Names encoded or decoded per piece of the cache's name section (keeps each string well under V8's limit) */
+const NAME_BATCH = 100000;
+/** Bytes of the name section decoded at a time when loading */
+const NAME_DECODE_BYTES = 64 * 1024 * 1024;
+const CLEAR_LINE = '\x1b[2K\r';
+/** First bytes of a cache file; the digit is the format version */
+const CACHE_MAGIC = 'TSFINDX1';
+/** Bits in VolumeIndex.flags */
+const IndexFlags = {
+    Directory: 0x01, /** A directory (searched beneath) */
+    Link: 0x02, /** A junction or symbolic link (never entered) */
+};
+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%.
+    -age N      Use a cached scan up to N minutes old (default ${DEFAULT_CACHE_MINUTES})
+    -fresh      Rescan the MFT even if a cached scan is young enough
+    -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, elevated prompt),
+which takes minutes rather than the hours a walk can take on a big drive. The scan is cached,
+compressed, in ${cacheDir()}, one file per volume, so further searches of
+any folder on that volume take seconds and need no elevation. The cache is a snapshot:
+changes since the scan are not seen until it is older than -age or -fresh is given. If a
+rescan is not possible (not elevated) an older cache is used, and the summary says how old.
+For a walk of a non-NTFS or network drive, use tswalk.
+
+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,
+        cacheMinutes: DEFAULT_CACHE_MINUTES, quiet: false,
+    };
+    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;
+            }
+            case '-age': {
+                const n = needValue();
+                if (!/^\d+(\.\d+)?$/.test(n))
+                    fail(`-age needs a number of minutes, not ${n}`);
+                options.cacheMinutes = parseFloat(n);
+                break;
+            }
+            case '-fresh':
+                options.cacheMinutes = 0;
+                break;
+            case '-q':
+                options.quiet = true;
+                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);
+}
+// ── Index: scan, save, load ────────────────────────────────────────
+function cacheDir() {
+    return path.join(os.tmpdir(), 'tsfind');
+}
+/**
+ * Read the MFT of the volume holding `top` and build tsfind's index of it. Throws MftError when
+ * the MFT cannot be read (not elevated, not NTFS); the caller decides what to do about that.
+ */
+async function scanToIndex(top, options) {
+    const { scanVolume } = await import('@bobfrankston/mftwalk');
+    const volume = await scanVolume(top, {
+        onProgress: (done, total) => progress(options, `MFT ${done.toLocaleString()} / ${total.toLocaleString()} records`),
+    });
+    clearProgress(options);
+    return indexFromVolume(volume);
+}
+/** Lay the volume out in preorder from the root, through mftwalk's public accessors */
+function indexFromVolume(volume) {
+    const order = [];
+    const parentOf = [];
+    // Depth-first; children pushed in reverse so they come out in the volume's own order.
+    const stack = [{ id: volume.root, parent: -1 }];
+    while (stack.length) {
+        const { id, parent } = stack.pop();
+        const at = order.length;
+        order.push(id);
+        parentOf.push(parent);
+        const kids = volume.children(id);
+        for (let k = kids.length - 1; k >= 0; k--) {
+            // NTFS's own files ($MFT, $Extend, ...) are invisible to readdir; leave them out likewise.
+            if (!volume.isMetafile(kids[k]))
+                stack.push({ id: kids[k], parent: at });
+        }
+    }
+    const count = order.length;
+    const index = {
+        count,
+        parent: Int32Array.from(parentOf),
+        subtreeEnd: new Int32Array(count),
+        flags: new Uint8Array(count),
+        size: new Float64Array(count),
+        mtime: new Float64Array(count),
+        names: new Array(count),
+    };
+    for (let i = 0; i < count; i++) {
+        const id = order[i];
+        index.flags[i] = (volume.isDirectory(id) ? IndexFlags.Directory : 0) | (volume.isLink(id) ? IndexFlags.Link : 0);
+        index.size[i] = volume.size(id);
+        index.mtime[i] = volume.mtime(id).getTime();
+        index.names[i] = i === 0 ? '' : volume.name(id);
+        index.subtreeEnd[i] = i + 1;
+    }
+    // In preorder a subtree ends where its last descendant's subtree ends; children come after
+    // parents, so one backward pass carries each end up to its parent.
+    for (let i = count - 1; i > 0; i--) {
+        const p = index.parent[i];
+        if (index.subtreeEnd[i] > index.subtreeEnd[p])
+            index.subtreeEnd[p] = index.subtreeEnd[i];
+    }
+    return index;
+}
+/** Bytes of a typed array, as a Buffer over the same memory */
+function bytesOf(array) {
+    return Buffer.from(array.buffer, array.byteOffset, array.byteLength);
+}
+/** The cache file's pieces, in order: magic, header length, header, then the arrays and names */
+function* cachePieces(index) {
+    const header = Buffer.from(JSON.stringify({ count: index.count }));
+    const headerLength = Buffer.alloc(4);
+    headerLength.writeUInt32LE(header.length);
+    yield Buffer.from(CACHE_MAGIC);
+    yield headerLength;
+    yield header;
+    yield bytesOf(index.parent);
+    yield bytesOf(index.subtreeEnd);
+    yield bytesOf(index.flags);
+    yield bytesOf(index.size);
+    yield bytesOf(index.mtime);
+    // Names end with \0, which no NTFS name contains.
+    for (let i = 0; i < index.count; i += NAME_BATCH) {
+        yield Buffer.from(index.names.slice(i, i + NAME_BATCH).join('\0') + '\0');
+    }
+}
+/**
+ * Save the index, zstd-compressed, and date the file to the start of the scan so its age is the
+ * snapshot's age. Written to a temporary name and renamed, so a reader never sees half a file.
+ */
+async function saveIndex(index, cachePath, scannedAt) {
+    await fp.mkdir(path.dirname(cachePath), { recursive: true });
+    const partial = cachePath + '.partial';
+    await pipeline(Readable.from(cachePieces(index)), createZstdCompress(), createWriteStream(partial));
+    await fp.utimes(partial, scannedAt, scannedAt);
+    await fp.rename(partial, cachePath);
+}
+async function loadIndex(cachePath) {
+    const chunks = [];
+    await pipeline(createReadStream(cachePath), createZstdDecompress(), async function* (source) {
+        for await (const chunk of source)
+            chunks.push(chunk);
+    });
+    const data = Buffer.concat(chunks);
+    chunks.length = 0;
+    if (data.toString('latin1', 0, CACHE_MAGIC.length) !== CACHE_MAGIC)
+        throw new Error(`${cachePath} is not a tsfind cache of this version`);
+    let at = CACHE_MAGIC.length;
+    const headerLength = data.readUInt32LE(at);
+    at += 4;
+    const { count } = JSON.parse(data.toString('utf8', at, at + headerLength));
+    at += headerLength;
+    // Copied out rather than viewed in place: the arrays' offsets in the buffer are not aligned.
+    const take = (array) => {
+        bytesOf(array).set(data.subarray(at, at + array.byteLength));
+        at += array.byteLength;
+        return array;
+    };
+    const index = {
+        count,
+        parent: take(new Int32Array(count)),
+        subtreeEnd: take(new Int32Array(count)),
+        flags: take(new Uint8Array(count)),
+        size: take(new Float64Array(count)),
+        mtime: take(new Float64Array(count)),
+        names: [],
+    };
+    while (at < data.length) {
+        let end = data.indexOf(0, Math.min(at + NAME_DECODE_BYTES, data.length - 1));
+        if (end < 0)
+            end = data.length - 1;
+        const piece = data.toString('utf8', at, end).split('\0');
+        for (const name of piece)
+            index.names.push(name);
+        at = end + 1;
+    }
+    if (index.names.length !== count)
+        throw new Error(`${cachePath} is damaged: ${index.names.length} names for ${count} entries`);
+    return index;
+}
+/**
+ * The volume label of the drive holding `top`, or '' if it has none or cannot be read.
+ * Node has no call for it, Get-Volume takes seconds, and reading it needs no elevation through
+ * cmd's vol, whose first line is "Volume in drive Y is <label>" (or "... has no label.").
+ * That wording is English Windows; on any other the label reads as '' and the cache is named
+ * "nolabel-<serial>", which still identifies the drive by its serial.
+ */
+function volumeLabel(top) {
+    const result = spawnSync('cmd', ['/d', '/c', 'vol', top.slice(0, 2)], { encoding: 'utf8' });
+    // Only the first line: the second, "Volume Serial Number is ...", also contains " is ".
+    const firstLine = (result.stdout ?? '').trim().split(/\r?\n/)[0];
+    const match = /^Volume in drive \w is (.*)$/.exec(firstLine);
+    return match ? match[1].trim() : '';
+}
+/**
+ * The index for the volume holding `top`: the cache if it is young enough, else a new scan
+ * (saved for next time), else, if the scan is not possible, an older cache with a note saying so.
+ */
+async function getIndex(top, options) {
+    // 2026-10-27 — Claude Code (Opus 5.5), at Bob's direction: the cache is named by volume label
+    // and volume serial number (20251211y-F860296A.idx.zst). The label says which drive a file is
+    // for; the serial keeps two drives with the same label apart. Either follows the drive to
+    // whatever letter it is mounted under. (Briefly the drive letter was used instead of the label.)
+    // On Windows fs.stat's dev is the volume serial number, and reading it needs no elevation.
+    const serial = (await fp.stat(top)).dev.toString(16).toUpperCase().padStart(8, '0');
+    const label = volumeLabel(top);
+    const cachePath = path.join(cacheDir(), `${label.replace(/[^\w.-]/g, '_') || 'nolabel'}-${serial}.idx.zst`);
+    let cacheAgeMs = -1;
+    try {
+        cacheAgeMs = Date.now() - (await fp.stat(cachePath)).mtimeMs;
+    }
+    catch (error) {
+        // Not lost: no cache file is the ordinary first-run case, and leads to a scan below.
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    // 2026-10-27 — Claude Code (Opus 5.5), at Bob's direction: say at the start which source is
+    // used and how old the cache is, not only in the summary at the end.
+    const announce = (text) => {
+        if (!options.quiet)
+            console.error(styleText(['blue'], text));
+    };
+    const volumeName = `${top.slice(0, 2).toUpperCase()} ${label ? `"${label}"` : '(no label)'} (serial ${serial})`;
+    const load = async (note) => {
+        announce(`Using the cached scan of ${volumeName}, ${elapsedText(cacheAgeMs)} old${note ? `; ${note}` : ''}: ${cachePath}`);
+        const index = await loadIndex(cachePath);
+        return { index, source: { scanned: false, ageMs: cacheAgeMs, cachePath, note } };
+    };
+    if (cacheAgeMs >= 0 && cacheAgeMs < options.cacheMinutes * 60000)
+        return load('');
+    announce(cacheAgeMs < 0
+        ? `Scanning the MFT of ${volumeName}; no cached scan yet`
+        : `Scanning the MFT of ${volumeName}; the cached scan is ${elapsedText(cacheAgeMs)} old` +
+            (options.cacheMinutes === 0 ? ' (-fresh)' : `, older than -age ${options.cacheMinutes} minutes`));
+    const { MftError } = await import('@bobfrankston/mftwalk');
+    const scannedAt = new Date();
+    let index;
+    try {
+        index = await scanToIndex(top, options);
+    }
+    catch (error) {
+        clearProgress(options);
+        if (!(error instanceof MftError))
+            throw error;
+        // Not swallowed: with an older cache the reason goes into the summary next to its age;
+        // without one it is the failure.
+        if (cacheAgeMs >= 0)
+            return load(`could not rescan (${error.message})`);
+        fail(`Cannot read the MFT: ${error.message}.\ntsfind reads the NTFS MFT (Windows, NTFS, elevated prompt); to walk a tree instead, use tswalk.`);
+    }
+    let note = '';
+    try {
+        if (!options.quiet && process.stderr.isTTY)
+            process.stderr.write('Saving the scan for later runs...');
+        await saveIndex(index, cachePath, scannedAt);
+        clearProgress(options);
+    }
+    catch (error) {
+        // Not lost: the search goes ahead on the scan in memory, and the summary says the cache was not saved.
+        clearProgress(options);
+        note = `not cached: ${error.code ?? error.message}`;
+    }
+    return { index, source: { scanned: true, ageMs: Date.now() - scannedAt.getTime(), cachePath, note } };
+}
+/** The entry for `top` in the index, by name from the root, case-insensitively as Windows does; -1 if absent */
+function lookupEntry(index, top) {
+    const rel = top.replace(/^[A-Za-z]:/, '');
+    let at = 0;
+    for (const part of rel.split(/[\\/]+/).filter(Boolean)) {
+        const want = part.toLowerCase();
+        let found = -1;
+        // Children of `at` are the entries right after it, each followed by its own subtree.
+        for (let child = at + 1; child < index.subtreeEnd[at]; child = index.subtreeEnd[child]) {
+            if (index.names[child].toLowerCase() === want) {
+                found = child;
+                break;
+            }
+        }
+        if (found < 0)
+            return -1;
+        at = found;
+    }
+    return at;
+}
+/** Full path of an entry, under the volume's current drive root */
+function entryPath(index, rootPath, entry) {
+    const parts = [];
+    for (let at = entry; at > 0; at = index.parent[at])
+        parts.push(index.names[at]);
+    return rootPath + parts.reverse().join('\\');
+}
+/** Hand each match beneath `start` to onFound; returns the number of directories searched */
+function searchIndex(index, start, rootPath, regexes, options, onFound) {
+    let dirs = 1;
+    const end = index.subtreeEnd[start];
+    for (let i = start + 1; i < end; i++) {
+        const flags = index.flags[i];
+        const isDir = (flags & (IndexFlags.Directory | IndexFlags.Link)) !== 0;
+        if (flags & IndexFlags.Directory && !(flags & IndexFlags.Link))
+            dirs++;
+        // Links have no entries beneath them in the index, so their contents are never searched.
+        const name = index.names[i];
+        if (!regexes.some(rx => rx.test(name)))
+            continue;
+        if (isDir && !options.dirs)
+            continue;
+        onFound({ path: entryPath(index, rootPath, i), name, size: isDir ? 0 : index.size[i], mtime: new Date(index.mtime[i]), 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 (process.platform !== 'win32')
+        fail('tsfind reads the NTFS MFT, so it runs on Windows only; to walk a tree, use tswalk.');
+    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}`);
+    }
+    const drive = /^([A-Za-z]):\\/.exec(top);
+    if (!drive)
+        fail(`${top} is not on a drive letter; tsfind reads a local NTFS volume's MFT. For a network path, use tswalk.`);
+    const rootPath = `${drive[1].toUpperCase()}:\\`;
+    // 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();
+    const { index, source } = await getIndex(top, options);
+    const entry = lookupEntry(index, top);
+    if (entry < 0) {
+        fail(`${top} is not in the ${source.scanned ? 'scan' : `cached scan from ${elapsedText(source.ageMs)} ago`}` +
+            `${source.scanned ? '' : '; -fresh rescans'}`);
+    }
+    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);
+    };
+    const dirs = searchIndex(index, entry, rootPath, 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';
+        const from = source.scanned
+            ? `MFT scanned${source.note ? `, ${source.note}` : ''}`
+            : `cached scan ${elapsedText(source.ageMs)} old${source.note ? `, ${source.note}` : ''}`;
+        console.error(`${matchCount.toLocaleString()} ${what}, ${formatBytes(matchBytes)}; ${dirs.toLocaleString()} directories searched; ` +
+            `${elapsedText(elapsed)} (${from})${options.outFile ? `; written to ${path.resolve(options.outFile)}` : ''}`);
+    }
+}
+if (import.meta.main) {
+    await main();
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@bobfrankston/tsfind",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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/mftwalk": "^0.1.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  ".dependencies": {
+    "@bobfrankston/mftwalk": "file:../mftwalk"
+  },
+  ".transformedSnapshot": {
+    "dependencies": {
+      "@bobfrankston/mftwalk": "^0.1.3"
+    }
+  }
+}