mediasnacks 0.11.1 → 0.12.0

package/.zsh/completions/_mediasnacks

@@ -11,42 +11,34 @@ _mediasnacks_commands=(
   'hev1tohvc1:Fixes video thumbnails not rendering in macOS Finder'
   'framediff:ffplay with a filter for diffing adjacent frames'
   'vdiff:Plays a video with the difference of two videos'
-  'vconcat:Concatenates videos',
-  'dlaudio: yt-dlp best audio',
-  'dlvideo: yt-dlp best video',
+  'vconcat:Concatenates videos'
+  'dlaudio: yt-dlp best audio'
+  'dlvideo: yt-dlp best video'
   'unemoji:Removes emojis from filenames'
   'rmcover:Removes cover art'
-  'curltime:Measures request response timings',
-  'gif:Video to GIF',
-  'vcut:Split video in two parts by time',
+  'curltime:Measures request response timings'
+  'gif:Video to GIF'
+  'vcut:Split video in two parts by time'
   'flattendir:Moves unique files to the top dir and deletes empty dirs'
 )
 
-_mediasnacks() {
-  if (( CURRENT == 2 )); then
-    _describe -t commands 'mediasnacks commands' _mediasnacks_commands
-    return
-  fi
+if (( CURRENT == 2 )); then
+	_describe -t commands 'mediasnacks commands' _mediasnacks_commands
+	return
+fi
 
-  local cmd="$words[2]"
-  case "$cmd" in
-    avif|resize|sqcrop|moov2front|dropdups|seqcheck|hev1tohvc1|framediff|vdiff|vconcat|dlaudio|dlvideo|unemoji|rmcover|curltime|gif|vcut|flattendir)
-      _files
-      ;;
-    qdir)
-      _files -/
-      ;;
-  esac
-}
-
-compdef _mediasnacks mediasnacks
+local cmd="$words[2]"
+case "$cmd" in
+	avif|resize|sqcrop|moov2front|dropdups|seqcheck|hev1tohvc1|framediff|vdiff|vconcat|dlaudio|dlvideo|unemoji|rmcover|curltime|gif|vcut|flattendir)
+		_files
+		;;
+	qdir)
+		_files -/
+		;;
+esac
 
 
 # INSTALL in: ~/.zshrc
 #fpath=(~/.zsh/completions $fpath)
 #zmodload zsh/complist
 #autoload -U compinit && compinit
-
-#function mediasnacks() {
-#  $HOME/work/mediasnacks/src/./cli.js "$@"
-#}

package/README.md

@@ -18,23 +18,46 @@ Commands:
 - `dropdups` Removes duplicate frames in a video
 - `seqcheck` Finds missing sequence number
 - `qdir` Sequentially runs all *.sh files in a folder
-- `hev1tohvc1`: Fixes video thumbnails not rendering in macOS Finder 
+- `hev1tohvc1`: Fixes video thumbnails not rendering in macOS Finder
 
 - `framediff`: Plays a video of adjacent frames diff
 - `vdiff`: Plays a video with the difference of two videos
 - `vconcat`: Concatenates videos
- 
+
 - `dlaudio`: yt-dlp best audio
 - `dlvideo`: yt-dlp best video
- 
+
 - `unemoji`: Removes emojis from filenames
-- `rmcover`: Removes cover art 
- 
+- `rmcover`: Removes cover art
+
 - `curltime`: Measures request response timings
 - `gif`: Video to GIF
 - `vcut`: Split video in two parts at a given time
- 
+
 - `flattendir`: Moves unique files to the top dir and deletes empty dirs
+
+### Glob Patterns and Literal Filenames
+
+Most commands accept glob patterns (like `*.png` or `file[234].png`) to match multiple files. By default, these patterns are expanded by Node.js to match existing files.
+
+To treat arguments as literal filenames instead of glob patterns, use the `--` (double dash) separator:
+
+```shell
+# This expands the pattern to match files: file2.png, file3.png, file4.png
+npx mediasnacks avif file[234].png
+
+# This treats the argument as a literal filename: "file[234].png"
+npx mediasnacks avif -- file[234].png
+
+# You can mix both: expand first pattern, treat second as literal
+npx mediasnacks avif file2.png -- file[234].png
+```
+
+This follows the standard POSIX convention where `--` stops option/pattern processing. Arguments after `--` are treated exactly as written, which is useful when:
+- Filenames contain special glob characters like `[`, `]`, `*`, or `?`
+- You want to pass a pattern to be processed later
+- Working with filenames that haven't been created yet
+
 <br/>
 
 ### Converting Images to AVIF

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mediasnacks",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Utilities for preparing videos, images, and audio for the web",
   "license": "MIT",
   "author": "Eric Fortis",

package/src/avif.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 import { join } from 'node:path'
-import { parseArgs } from 'node:util'
 
-import { replaceExt, lstat, globAll } from './utils/fs-utils.js'
+import { replaceExt, lstat } from './utils/fs-utils.js'
+import { parseArgsWithGlobs } from './utils/args-with-globs.js'
 import { ffmpeg, assertUserHasFFmpeg } from './utils/ffmpeg.js'
 
 
@@ -17,13 +17,12 @@ Converts images to AVIF.
 async function main() {
 	await assertUserHasFFmpeg()
 
-	const { values, positionals } = parseArgs({
+	const { values, files } = await parseArgsWithGlobs({
 		options: {
 			'output-dir': { type: 'string', default: '' },
 			overwrite: { short: 'y', type: 'boolean', default: false },
 			help: { short: 'h', type: 'boolean', default: false },
-		},
-		allowPositionals: true
+		}
 	})
 
 	if (values.help) {
@@ -31,11 +30,11 @@ async function main() {
 		process.exit(0)
 	}
 
-	if (!positionals.length)
+	if (!files.length)
 		throw new Error('No images specified. See npx mediasnacks avif --help')
 
 	console.log('AVIF…')
-	for (const file of await globAll(positionals))
+	for (const file of files)
 		await toAvif({
 			file,
 			outFile: join(values['output-dir'], replaceExt(file, 'avif')),

package/src/dropdups.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
 
-import { parseArgs } from 'node:util'
 import { resolve, parse, format } from 'node:path'
 
-import { globAll } from './utils/fs-utils.js'
+import { parseArgsWithGlobs } from './utils/args-with-globs.js'
 import { ffmpeg, assertUserHasFFmpeg, run } from './utils/ffmpeg.js'
 
 
@@ -34,13 +33,12 @@ Options:
 
 async function main() {
 	await assertUserHasFFmpeg()
-	
-	const { values, positionals } = parseArgs({
+
+	const { values, files } = await parseArgsWithGlobs({
 		options: {
 			'bad-frame-number': { short: 'n', type: 'string', default: '' },
 			help: { short: 'h', type: 'boolean', default: false },
-		},
-		allowPositionals: true
+		}
 	})
 
 	if (values.help) {
@@ -48,7 +46,7 @@ async function main() {
 		process.exit(0)
 	}
 
-	if (!positionals.length)
+	if (!files.length)
 		throw new Error('No video specified. See npx mediasnacks dropdups --help')
 
 	let nBadFrame = values['bad-frame-number']
@@ -56,7 +54,7 @@ async function main() {
 		throw new Error('Invalid --bad-frame-number. It must be a positive integer.')
 
 	console.log('Dropping Duplicate Frames…')
-	for (const file of await globAll(positionals))
+	for (const file of files)
 		await drop(resolve(file), nBadFrame)
 }
 

package/src/hev1tohvc1.js

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 
-import { parseArgs } from 'node:util'
-
-import { uniqueFilenameFor, overwrite, globAll } from './utils/fs-utils.js'
+import { uniqueFilenameFor, overwrite } from './utils/fs-utils.js'
+import { parseArgsWithGlobs } from './utils/args-with-globs.js'
 import { videoAttrs, ffmpeg, assertUserHasFFmpeg } from './utils/ffmpeg.js'
 
 
@@ -18,12 +17,13 @@ by changing the container’s sample entry code from HEV1 to HVC1.
 async function main() {
 	await assertUserHasFFmpeg()
 
-	const { positionals } = parseArgs({ allowPositionals: true })
-	if (!positionals.length)
+	const { files } = await parseArgsWithGlobs({})
+
+	if (!files.length)
 		throw new Error(USAGE)
 
 	console.log('HEV1 to HVC1…')
-	for (const file of await globAll(positionals))
+	for (const file of files)
 		await toHvc1(file)
 }
 

package/src/moov2front.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
 
-import { parseArgs } from 'node:util'
-
 import { ffmpeg, assertUserHasFFmpeg } from './utils/ffmpeg.js'
-import { uniqueFilenameFor, overwrite, globAll } from './utils/fs-utils.js'
+import { uniqueFilenameFor, overwrite } from './utils/fs-utils.js'
+import { parseArgsWithGlobs } from './utils/args-with-globs.js'
 
 
 const USAGE = `
@@ -17,12 +16,13 @@ Files are overwritten.
 async function main() {
 	await assertUserHasFFmpeg()
 
-	const { positionals } = parseArgs({ allowPositionals: true })
-	if (!positionals.length)
+	const { files } = await parseArgsWithGlobs({})
+
+	if (!files.length)
 		throw new Error(USAGE)
 
 	console.log('Optimizing video for progressive download…')
-	for (const file of await globAll(positionals))
+	for (const file of files)
 		await moov2front(file)
 }
 

package/src/resize.js

@@ -2,9 +2,9 @@
 
 import { join } from 'node:path'
 import { rename } from 'node:fs/promises'
-import { parseArgs } from 'node:util'
 
-import { isFile, uniqueFilenameFor, globAll } from './utils/fs-utils.js'
+import { isFile, uniqueFilenameFor } from './utils/fs-utils.js'
+import { parseArgsWithGlobs } from './utils/args-with-globs.js'
 import { ffmpeg, videoAttrs, assertUserHasFFmpeg } from './utils/ffmpeg.js'
 
 
@@ -30,15 +30,14 @@ Details:
 async function main() {
 	await assertUserHasFFmpeg()
 
-	const { values, positionals } = parseArgs({
+	const { values, files } = await parseArgsWithGlobs({
 		options: {
 			width: { type: 'string', default: '-2' },
 			height: { type: 'string', default: '-2' },
 			'output-dir': { type: 'string', default: '' },
 			overwrite: { short: 'y', type: 'boolean', default: false },
 			help: { short: 'h', type: 'boolean', default: false },
-		},
-		allowPositionals: true
+		}
 	})
 
 	if (values.help) {
@@ -52,12 +51,12 @@ async function main() {
 	if (width <= 0 && height <= 0)
 		throw new Error('--width or --height need to be greater than 0')
 
-	if (!positionals.length)
+	if (!files.length)
 		throw new Error('No video files specified')
 
 
 	console.log('Resizing…')
-	for (const file of await globAll(positionals))
+	for (const file of files)
 		await resize({
 			file,
 			outFile: join(values['output-dir'], file),

package/src/sqcrop.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 import { join } from 'node:path'
-import { parseArgs } from 'node:util'
 
 import { rename } from 'node:fs/promises'
 import { ffmpeg, assertUserHasFFmpeg } from './utils/ffmpeg.js'
-import { replaceExt, lstat, globAll, uniqueFilenameFor } from './utils/fs-utils.js'
+import { replaceExt, lstat, uniqueFilenameFor } from './utils/fs-utils.js'
+import { parseArgsWithGlobs } from './utils/args-with-globs.js'
 
 
 const USAGE = `
@@ -18,13 +18,12 @@ Square crops images
 async function main() {
 	await assertUserHasFFmpeg()
 
-	const { values, positionals } = parseArgs({
+	const { values, files } = await parseArgsWithGlobs({
 		options: {
 			'output-dir': { type: 'string', default: '' },
 			overwrite: { short: 'y', type: 'boolean', default: false },
 			help: { short: 'h', type: 'boolean', default: false },
-		},
-		allowPositionals: true
+		}
 	})
 
 	if (values.help) {
@@ -32,11 +31,11 @@ async function main() {
 		process.exit(0)
 	}
 
-	if (!positionals.length)
+	if (!files.length)
 		throw new Error('No images specified. See npx mediasnacks sqcrop --help')
 
 	console.log('Cropping…')
-	for (const file of await globAll(positionals))
+	for (const file of files)
 		await sqcrop({
 			file,
 			outFile: join(values['output-dir'], file),

package/src/utils/args-with-globs.js

@@ -0,0 +1,61 @@
+import { promisify } from 'node:util'
+import { parseArgs } from 'node:util'
+import { glob as _glob } from 'node:fs'
+
+
+const glob = promisify(_glob)
+
+export async function parseArgsWithGlobs(config) {
+	const { values, positionals, tokens } = parseArgs({
+		allowPositionals: true,
+		...config,
+		tokens: true
+	})
+
+	const files = await globAll(positionals, tokens)
+
+	return { values, positionals, tokens, files }
+}
+
+export async function globAll(arr, tokens) {
+	const terminatorIndex = findTerminatorIndex(tokens)
+	const set = new Set()
+
+	if (terminatorIndex >= 0) {
+		// Glob arguments before the terminator
+		const beforeTerminator = arr.slice(0, terminatorIndex)
+		const afterTerminator = arr.slice(terminatorIndex)
+
+		for (const g of beforeTerminator)
+			for (const file of await glob(g))
+				set.add(file)
+
+		// Add arguments after terminator as literal strings
+		for (const literal of afterTerminator)
+			set.add(literal)
+	} else {
+		// No terminator, glob everything (current behavior)
+		for (const g of arr)
+			for (const file of await glob(g))
+				set.add(file)
+	}
+
+	return Array.from(set)
+}
+
+function findTerminatorIndex(tokens) {
+	if (!tokens) return -1
+	for (const token of tokens) {
+		if (token.kind === 'option-terminator') {
+			// Find the position in the positionals array
+			// The terminator itself is not in positionals, so we count preceding positionals
+			let positionalCount = 0
+			for (const t of tokens) {
+				if (t === token) break
+				if (t.kind === 'positional') positionalCount++
+			}
+			return positionalCount
+		}
+	}
+	return -1
+}

package/src/utils/args-with-globs.test.js

@@ -0,0 +1,153 @@
+import { equal, deepEqual } from 'node:assert/strict'
+import test, { describe, before, after } from 'node:test'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { globAll, parseArgsWithGlobs } from './args-with-globs.js'
+
+
+describe('globAll with token terminator', () => {
+	let testDir
+	const testFiles = ['test-file2.png', 'test-file3.png', 'test-file4.png', 'other-file.png']
+
+	before(async () => {
+		testDir = await mkdtemp(join(tmpdir(), 'glob-test-'))
+		for (const file of testFiles) {
+			await writeFile(join(testDir, file), '')
+		}
+	})
+
+	after(async () => {
+		await rm(testDir, { recursive: true, force: true })
+	})
+
+	test('globs patterns when no terminator present', async () => {
+		const pattern = join(testDir, 'test-file[234].png')
+		const result = await globAll([pattern])
+		const expected = testFiles.slice(0, 3).map(f => join(testDir, f)).sort()
+		deepEqual(result.sort(), expected)
+	})
+
+	test('globs patterns before terminator and keeps literals after', async () => {
+		const pattern = join(testDir, 'test-file[234].png')
+		const literal = 'my-literal-file[234].png'
+
+		// Simulate tokens from parseArgs with terminator
+		const tokens = [
+			{ kind: 'positional', index: 0, value: pattern },
+			{ kind: 'option-terminator', index: 1 },
+			{ kind: 'positional', index: 1, value: literal }
+		]
+
+		const result = await globAll([pattern, literal], tokens)
+		const expected = [
+			...testFiles.slice(0, 3).map(f => join(testDir, f)),
+			literal
+		].sort()
+		deepEqual(result.sort(), expected)
+	})
+
+	test('keeps all arguments literal when terminator is first', async () => {
+		const literal1 = 'literal-file[234].png'
+		const literal2 = 'another-file[567].png'
+
+		// Simulate tokens where terminator comes before all positionals
+		const tokens = [
+			{ kind: 'option-terminator', index: 0 },
+			{ kind: 'positional', index: 0, value: literal1 },
+			{ kind: 'positional', index: 1, value: literal2 }
+		]
+
+		const result = await globAll([literal1, literal2], tokens)
+		deepEqual(result.sort(), [literal1, literal2].sort())
+	})
+
+	test('handles no terminator with tokens (backwards compat)', async () => {
+		const pattern = join(testDir, 'test-file[234].png')
+
+		// Tokens without terminator
+		const tokens = [
+			{ kind: 'positional', index: 0, value: pattern }
+		]
+
+		const result = await globAll([pattern], tokens)
+		const expected = testFiles.slice(0, 3).map(f => join(testDir, f)).sort()
+		deepEqual(result.sort(), expected)
+	})
+
+	test('handles undefined tokens (backwards compat)', async () => {
+		const pattern = join(testDir, 'test-file[234].png')
+		const result = await globAll([pattern], undefined)
+		const expected = testFiles.slice(0, 3).map(f => join(testDir, f)).sort()
+		deepEqual(result.sort(), expected)
+	})
+
+	test('handles empty arrays', async () => {
+		const result = await globAll([])
+		deepEqual(result, [])
+	})
+
+	test('deduplicates results', async () => {
+		const pattern = join(testDir, 'test-file2.png')
+		const result = await globAll([pattern, pattern])
+		deepEqual(result, [join(testDir, 'test-file2.png')])
+	})
+})
+
+describe('parseArgsWithGlobs', () => {
+	let testDir
+	const testFiles = ['file1.png', 'file2.png', 'file3.png']
+
+	before(async () => {
+		testDir = await mkdtemp(join(tmpdir(), 'parse-args-test-'))
+		for (const file of testFiles) {
+			await writeFile(join(testDir, file), '')
+		}
+	})
+
+	after(async () => {
+		await rm(testDir, { recursive: true, force: true })
+	})
+
+	test('parses args and globs files in one call', async () => {
+		const pattern = join(testDir, 'file[12].png')
+		const { values, files } = await parseArgsWithGlobs({
+			args: ['--output-dir', '/tmp', pattern],
+			options: {
+				'output-dir': { type: 'string' }
+			}
+		})
+
+		equal(values['output-dir'], '/tmp')
+		deepEqual(files.sort(), [
+			join(testDir, 'file1.png'),
+			join(testDir, 'file2.png')
+		].sort())
+	})
+
+	test('respects verbatim token in parseArgsWithGlobs', async () => {
+		const pattern = join(testDir, 'file[12].png')
+		const literal = 'literal-file[99].png'
+		const { files } = await parseArgsWithGlobs({
+			args: [pattern, '--', literal]
+		})
+
+		deepEqual(files.sort(), [
+			join(testDir, 'file1.png'),
+			join(testDir, 'file2.png'),
+			literal
+		].sort())
+	})
+
+	test('returns empty files array when no positionals', async () => {
+		const { files, values } = await parseArgsWithGlobs({
+			args: ['--flag'],
+			options: {
+				flag: { type: 'boolean' }
+			}
+		})
+
+		equal(values.flag, true)
+		deepEqual(files, [])
+	})
+})

package/src/utils/fs-utils.js

@@ -1,20 +1,9 @@
-import { promisify } from 'node:util'
 import { randomUUID } from 'node:crypto'
 import { unlink, rename } from 'node:fs/promises'
 import { dirname, extname, join } from 'node:path'
-import { lstatSync, glob as _glob } from 'node:fs'
+import { lstatSync } from 'node:fs'
 
 
-const glob = promisify(_glob)
-
-export async function globAll(arr) {
-	const set = new Set()
-	for (const g of arr)
-		for (const file of await glob(g))
-			set.add(file)
-	return Array.from(set)
-}
-
 export const lstat = f => lstatSync(f, { throwIfNoEntry: false })
 export const isFile = path => lstat(path)?.isFile()
 
@@ -26,7 +15,7 @@ export const replaceExt = (f, ext) => {
 	return parts.join('.')
 }
 
-export const uniqueFilenameFor = file => 
+export const uniqueFilenameFor = file =>
 	join(dirname(file), randomUUID() + extname(file))
 
 

package/src/utils/fs-utils.test.js

@@ -4,18 +4,18 @@ import { replaceExt } from './fs-utils.js'
 
 
 describe('replaceExt', () => {
-	test('replaces a simple extension', () => 
+	test('replaces a simple extension', () =>
 		equal(replaceExt('file.txt', 'md'), 'file.md'))
 
-	test('replaces a multi-part extension', () => 
+	test('replaces a multi-part extension', () =>
 		equal(replaceExt('archive.tar.gz', 'zip'), 'archive.tar.zip'))
 
-	test('adds extension when none exists', () => 
+	test('adds extension when none exists', () =>
 		equal(replaceExt('README', 'md'), 'README.md'))
 
 	test('handles empty filename', () =>
 		equal(replaceExt('', 'ext'), '.ext'))
-	
+
 	test('handles dot-files', () =>
 		equal(replaceExt('.env', 'txt'), '.env.txt'))
 })