| name | scan-source |
| description | Use when the user wants to inventory a source directory before burning it to optical media — produces a manifest of every file with size and mtime plus a summary. |
Scan Source
Walk a source directory, emit manifest.json (one entry per file: path, size, mtime), and print a human summary (total size, file count, largest file).
When to use
- First step of any optical archive job, before batching or burning.
- Whenever the user asks "how big is this folder for burning" or "give me an inventory of X".
Inputs to gather
- Source path (absolute). Required.
- Optional include/exclude globs (e.g.
--exclude '*.tmp').
- Output workspace — default to job folder under the resolver below.
Procedure
- Resolve workspace:
WORKSPACE="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/batch-optical-archivist/jobs/$(date +%Y%m%d-%H%M)". Create it if missing.
- Validate source path exists and is readable.
- Walk the tree. Prefer a short Python script for clean JSON; fall back to
find <src> -type f -printf '%p\t%s\t%T@\n' if Python is unavailable.
- Apply include/exclude globs if given.
- Write
$WORKSPACE/manifest.json as a JSON array of {path, size, mtime} (path relative to source root).
- Compute and print: total bytes, file count, largest single file, top 5 largest, and total size in MiB and GiB.
- Run
du -sh <src> as a cross-check and surface mismatches.
Output / side effects
$WORKSPACE/manifest.json- Stdout summary the user can eyeball before proceeding to
plan-batches.
Safety / constraints
- Read-only operation; never writes into the source tree.
- Skip unreadable files with a warning rather than aborting.
