scan-source

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

1. 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.
2. Validate source path exists and is readable.
3. 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.
4. Apply include/exclude globs if given.
5. Write $WORKSPACE/manifest.json as a JSON array of {path, size, mtime} (path relative to source root).
6. Compute and print: total bytes, file count, largest single file, top 5 largest, and total size in MiB and GiB.
7. 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.