cmd

Documentation

Overview

changelog.go — implements the `movie changelog` command. Reads CHANGELOG.md from the binary's directory (or repo root) and prints the latest version block or the full changelog.

constants.go — shared string constants to avoid magic strings.

doctor.go — `movie doctor` command.

Diagnostic for the updater pipeline. Surfaces deployPath/PATH mismatches, missing PATH entries, stale handoff workers, and version drift between the active binary and the deployed one — exactly the failure modes cataloged in spec/09-app-issues/08-updater-stale-handoff-loop-full-rca.md.

Usage:

movie doctor          # diagnose only (human output)
movie doctor --fix    # diagnose + auto-repair fixable findings
movie doctor --json   # machine-readable JSON for CI/scripts

Exit codes:

0 = all OK
2 = errors found
3 = fixable warnings only (no errors)

exit_codes.go — distinct, documented exit codes for scriptable undo/redo runs. Importable from anywhere in cmd/.

Stable contract — DO NOT renumber. CI scripts depend on these values.

Range allocation:

0       success / nothing to do
2       generic error (DB open, FS failure, etc.)
10..19  user declined / canceled
20..29  filter / scope produced empty result

Codes 1 and >127 are reserved (1 is shell convention for unspecified failure; 128+ collides with signal exit codes).

hello.go — implements the `movie hello` command.

history_summary.go — shared post-operation summary for movie undo/redo.

Whenever an undo/redo flow finishes (single op, batch, or just `--list`), we want the user to see four numbers:

matched   — rows that passed the dir scope + glob filter
executed  — rows we actually undid/redid (matched − failed for batch;
            1 for single op when it succeeded)
failed    — rows where the filesystem operation errored out
skipped   — rows that exist in the DB but were dropped by the
            dir-scope or glob filter (i.e. "out of scope")

Single-op flows just set Matched=1 + Executed=1 (or Failed=1) and compute Skipped from raw vs filtered counts.

imdb_cache_adapter.go — adapts *db.DB to the tmdb.ImdbCache interface.

Lives in cmd/ so the db package stays independent of tmdb and vice-versa. Wire it up at every TMDb client construction site that has a *db.DB in scope:

client := tmdb.NewClientWithToken(...)
client.SetImdbCache(newImdbCacheAdapter(database))

imdb_cache_attach.go — shared helper to optionally attach the IMDb cache to a TMDb client based on a --no-cache style flag.

Used by `movie rescan` and `movie rescan-failed` so a user can force a fresh DuckDuckGo + TMDb /find lookup without having to clear the cache (and lose every other cached hit) first.

log_init_helper.go — shared helper that initializes errlog for long-running commands (scan, rescan, rescan-failed). When keepLogs is false the logs directory is wiped so each run starts with a clean error.txt; when true the previous run's log is preserved (useful for diffing two consecutive runs).

movie_cache.go — `movie cache imdb` command and its subcommands (list, clear, clear-misses) for inspecting and invalidating the ImdbLookupCache without touching the SQLite file directly.

movie_cache_backfill.go — `movie cache imdb backfill` subcommand.

Walks every cached HIT row whose TmdbId is 0 (legacy v2 rows from before migration v3, plus partial hits where the /find call never resolved) and re-runs TMDb /find?external_source=imdb_id for each one. On success the cache row is updated in place with the resolved TmdbId + MediaType so the next run becomes a fully warm hit and skips both DuckDuckGo AND /find.

Failures are kept as partial hits (TmdbId stays 0); they will be retried on the next backfill or on the next normal scan that happens to hit the same title.

movie_cache_forget.go — `movie cache imdb forget <cleanTitle> [year]` subcommand. Deletes one row from the ImdbLookupCache so the next scan re-resolves that single title from scratch (DuckDuckGo + /find) without nuking the entire cache or running with --no-cache for every title.

movie_cd.go — movie cd [folder] — print scanned folder path for shell cd

movie_cleanup.go — find and remove stale DB entries where files no longer exist.

movie_config.go — movie config

movie_db.go — movie db: print resolved database path for debugging

movie_db_version.go — movie db version: prints applied schema migrations.

movie_discover.go — movie discover [genre]

movie_duplicates.go — detect duplicate media entries in the library. Supports detection by TMDb ID, filename, or file size.

movie_export.go — movie export Dumps the media table as JSON with optional storage stats and genre breakdown.

movie_fetch_details.go — shared TMDb detail+credit fetching helpers

-- Shared helpers --

fetchMovieDetails(client, tmdbID, m)  — populate Media with TMDb movie details + credits
fetchTVDetails(client, tmdbID, m)     — populate Media with TMDb TV details + credits

Consumers: movie_scan_process.go, movie_info.go, movie_search.go

These helpers centralize all TMDb detail+credit fetching so that scan, info, and search share identical enrichment logic. Any change to field mapping or credit extraction should happen here only.

Error handling per spec/02-error-manage-spec/04-runtime-error-handling.md: - Network/timeout errors are logged as warnings, not fatal - Each sub-request (details, credits, videos) fails independently - The scan continues with whatever data was successfully fetched

movie_history.go — movie history: unified view of all tracked operations.

Shows moves, renames, scans, deletions, popouts, and rescans from both move_history and action_history tables.

Flags:

--type <type>    Filter by type: move, scan, delete, popout, rescan, all (default: all)
--batch <id>     Show all actions in a specific batch
--limit <n>      Max records to show (default: 20)
--format <fmt>   Output format: default, json, table

movie_history_collect.go — data collection and helpers for history command.

movie_history_table.go — table-formatted output for unified history

movie_info.go — movie info <id-or-title>

Accepts a numeric ID (from library) or a title string. Checks local DB first; if not found by title, falls back to TMDb API, fetches full details, stores in DB, then displays.

Shared TMDb fetch helpers (fetchMovieDetails, fetchTVDetails) live in movie_fetch_details.go.

movie_info_helpers.go — helpers shared by movie info and scan for thumbnail downloads.

movie_info_json.go — JSON output for movie info

movie_info_table.go — table-formatted output for movie info

movie_logs.go — movie logs: display recent error logs from the database

movie_ls.go — movie ls

movie_ls_detail.go — detail view and helpers for movie ls

movie_ls_table.go — table-formatted output for movie ls

movie_move.go — movie move

movie_move_batch.go — batch and interactive move flows.

movie_move_helpers.go — shared helpers for move/rename/undo operations. Consumers: movie_move.go, movie_rename.go, movie_undo.go, movie_stats.go Do NOT duplicate move/size/path logic elsewhere — use these helpers.

movie_play.go — movie play <id>

movie_popout.go — movie popout: extract nested video files to root directory.

Discovers video files inside subfolders of a target directory and moves them up to the root level with clean filenames. After the moves, any subfolder that has no remaining media is COMPACTED into <root>/.temp/ (a non-destructive replacement for the old delete-prompt). Each move and each compact is tracked in move_history and action_history for full undo/redo support.

Default behavior (no [directory] argument):

popout uses the current working directory. It will NEVER silently exit
just because no path was given — see mem://constraints/cwd-default-rule.

Flags:

--dry-run         Preview without moving anything
--no-rename       Keep original filename
--depth N         Max subfolder depth (default 3)
--auto-compact    Skip the y/N prompt and compact non-media folders into
                  <root>/.temp/ automatically. Default: prompt with y/N.

movie_popout_cleanup.go — folder compaction phase for popout command.

REPLACES the previous destructive "remove folder" prompt. After media files are popped out to root, any subfolder that:

1. was originally empty, OR
2. contains zero media files (only samples/subs/.nfo/.txt/etc.)

is MOVED into <root>/.temp/ instead of deleted. Each move is recorded as a FileActionCompact action so `movie undo --batch <id>` can restore the folder to its original location.

User-facing surface:

• With no flag → interactive prompt: y / s (select) / n (keep) / l (list)
• With --auto-compact → no prompt; every qualifying folder goes to .temp/

See spec/09-app-issues/08-popout-silent-failure.md and mem://features/popout-spec.

movie_popout_discover.go — discovery and execution for popout command.

movie_popout_restore.go — undo/redo handlers for FileActionCompact entries.

When `movie popout` compacts a non-media folder it records a row with FileActionCompact and a JSON snapshot of the form:

{"original_path":"/abs/path/Folder","compact_path":"/abs/path/.temp/Folder"}

This file owns the symmetric filesystem operations:

• undoCompact: move <compact_path> back to <original_path>
• redoCompact: move <original_path> forward into <compact_path>

Both update IsReverted on the action row so list/redo/undo flows stay consistent. See mem://features/popout-spec.

movie_popout_summary.go — final summary report for the popout command.

Printed at the very end of every popout run (success, partial, or zero) so the user gets one consolidated bottom-line: how many files were flattened to the root and how many subfolders were compacted into <root>/.temp/. The batch ID is included so it can be fed straight into `movie undo --batch <id>` if needed.

movie_redo.go — movie redo: re-applies the last reverted operation.

Supports redoing:

• File moves/renames (from move_history, IsReverted=1)
• Action history ops (from action_history, IsReverted=1)

Flags:

--list           Show recent redoable actions
--id <id>        Redo a specific action_history record
--move-id <id>   Redo a specific move_history record
--batch          Redo the entire last reverted batch

movie_redo_exec.go — execution helpers for redo command.

movie_redo_handlers.go — redo subcommand handlers (list, by-id, batch, last).

movie_rename.go — movie rename

movie_rescan.go — movie rescan — re-fetches TMDb data for entries with missing metadata

movie_rescan_failed.go — re-runs TMDb lookup ONLY for rows still missing TmdbId, using the new SearchWithFallback chain (progressive trim → DuckDuckGo→IMDb→TMDb /find).

movie_rescan_helper.go — shared rescan logic used by both scan and rescan commands

movie_resolve.go — shared media resolver

-- Shared helper exported from this file --

resolveMediaByQuery(db, query) (*Media, error)
    Resolves a media item from the local DB by numeric ID or fuzzy
    title match (exact → prefix → first result).

Consumers: movie_info.go, movie_play.go, movie_ls.go (detail view)

All commands that accept an <id-or-title> argument should use this helper to keep resolution logic consistent. Do NOT duplicate the ID-parse → exact-match → prefix-match → fallback chain elsewhere.

movie_rest.go — movie rest: starts a local HTTP server for the library API

movie_rest_dashboard.go — JSON endpoints powering the HTML dashboard's filter sidebar, paginated card list, and per-item modal details.

movie_rest_details.go — modal payload endpoint: /api/media/{id}/details.

movie_rest_export.go — exports the current dashboard list filter results as CSV or JSON.

GET /api/dashboard/export?format=csv|json&<dashboard list filters>

Reuses the same query parsing and filtering pipeline as /api/dashboard/list so the exported rows always match what the user sees.

movie_rest_handlers.go — additional REST API handlers for tags, similar, and watched.

movie_rest_report.go — HTML report rendering and media CRUD handlers.

movie_scan.go — movie scan [folder] — command definition and orchestrator

movie_scan_collect.go — video file discovery for movie scan

movie_scan_helpers.go — shared helpers for movie scan (dir resolution, output dirs, print)

movie_scan_helpers_print.go — print helpers for scan footer (extracted from movie_scan_helpers.go)

movie_scan_html.go — generates report.html from the embedded template after a scan.

movie_scan_json.go — JSON metadata file generation during scan

-- Shared helper exported from this file --

writeScanJSON(basePath, media)  — write per-item JSON metadata to data/json/<slug>/

Consumers: movie_scan.go (called after each successful scan+metadata fetch)

Do NOT duplicate JSON metadata writing elsewhere — use writeScanJSON.

movie_scan_json_output.go — JSON stdout output for movie scan --format json

movie_scan_loop.go — main scan processing loop extracted from movie_scan.go.

movie_scan_process.go — per-file processing and TMDb enrichment for movie scan

movie_scan_process_helpers.go — extracted helpers for processVideoFile.

movie_scan_summary.go — writes .movie-output/summary.json after a scan.

movie_scan_table.go — table-formatted output for movie scan

movie_scan_watch.go — file watcher for movie scan --watch

movie_search.go — movie search <name> Searches TMDb API, fetches full details, and saves to local database.

movie_search_json.go — JSON output for movie search

movie_search_save.go — save selected search result to database and print summary

movie_search_table.go — table-formatted output for movie search

movie_stats.go — movie stats

movie_stats_table.go — table-formatted output for movie stats

movie_suggest.go — movie suggest [N]

movie_suggest_helpers.go — helper functions for movie suggest command.

movie_tag.go — movie tag [add|remove|list]

movie_tmdb.go — TMDb credential helpers for interactive commands

movie_undo.go — movie undo: reverts the last state-changing operation.

Supports undoing:

• File moves/renames (from move_history)
• Deletions (from action_history)
• Scan additions (from action_history)
• Scan removals (from action_history)
• Rescan updates (from action_history)

Flags:

--list           Show recent undoable actions
--id <id>        Undo a specific action_history record
--batch          Undo entire last batch
--move-id <id>   Undo a specific move_history record

movie_undo_exec.go — execution helpers for undo command.

movie_undo_handlers.go — undo subcommand handlers (list, by-id, batch, last).

movie_watch.go — manage a personal watchlist (to-watch / watched).

movie_watch_sync.go — watchlist export/import for backup and sharing.

path_resolver.go — universal CWD-default resolver for ALL movie commands.

-- Shared helper exported from this file --

ResolveTargetDir(args, home) (string, error)
    Resolves the target directory for any command that takes an
    optional [path] argument. Behavior:
      1. args[0] non-empty  → expand ~ and return.
      2. args[0] missing    → return os.Getwd() (current working dir).
      3. Any error          → loud apperror, NEVER silent empty string.

This helper EXISTS specifically to kill silent-failure bugs where a command exits with no error because an interactive prompt returned "". See spec/09-app-issues/08-popout-silent-failure.md.

Project rule (mem://constraints/cwd-default-rule):

"If a command takes an optional path argument and none is given, it
 MUST default to the current working directory. NEVER prompt silently,
 NEVER return empty, NEVER swallow the error."

Consumers (all 21+ commands accepting an optional path):

movie scan, movie move, movie popout, movie rename, movie cleanup,
movie duplicates, movie rescan, movie cache, movie cache backfill,
movie cache forget, ... (any command that scans or operates on files).

Do NOT duplicate the args[0] / cwd / expandHome chain elsewhere — use this helper.

path_scope.go — shared path-scoping helpers for history commands (movie undo / movie redo / future history filters).

Rule (mem://constraints/cwd-default-rule + this file):

movie undo  [path]   → scope = path or cwd. --global to override.
movie redo  [path]   → scope = path or cwd. --global to override.

"In scope" means: ANY path stored on the action (FromPath, ToPath, MediaSnapshot.original_path / compact_path / file_path) is rooted under the resolved scope directory.

root.go — defines the root cobra command and wires all subcommands together. The only logic here is registering child commands and calling Execute().

scan_stats.go — ScanStats struct shared by scan report functions.

self_replace.go — `movie self-replace` command. One-shot bootstrap that atomically copies the freshly deployed binary over the active PATH binary, breaking out of stale-handoff loops where the active binary points at a different drive than powershell.json's deployPath.

Usage:

movie self-replace                           # auto: from deployPath, to active PATH
movie self-replace --from D:\bin-run\movie.exe
movie self-replace --from <src> --to <dst>

See spec/09-app-issues/07-updater-deploypath-vs-path-mismatch.md.

types.go — shared option structs for functions with >3 parameters.

update.go — implements the `movie update` command. Uses the copy-and-handoff pattern from gitmap-v2 to bypass Windows file locks. See spec/13-self-update-app-update/ for full architecture documentation.

version.go — implements the `movie version` command.

Index

• Constants
• func ActionInScope(a db.ActionRecord, scope string) bool
• func ActionMatchesGlobs(a db.ActionRecord, f ScopeFilter) bool
• func Execute()
• func FilterActions(actions []db.ActionRecord, scope string) []db.ActionRecord
• func FilterActionsWith(actions []db.ActionRecord, f ScopeFilter) []db.ActionRecord
• func FilterMoves(moves []db.MoveRecord, scope string) []db.MoveRecord
• func FilterMovesWith(moves []db.MoveRecord, f ScopeFilter) []db.MoveRecord
• func MoveFile(src, dst string) error
• func MoveInScope(m db.MoveRecord, scope string) bool
• func MoveMatchesGlobs(m db.MoveRecord, f ScopeFilter) bool
• func MustResolveTargetDir(args []string, home string) string
• func ResolveTargetDir(args []string, home string) (string, error)
• type AppendUniqueInput
• type BatchMovePreview
• type CleanupContext
• type DiscoverGenreInput
• type DryRunCounters
• type DryRunInput
• type DryRunOutput
• type FillRecoInput
• type FinalizeScanInput
• type FindMoveMediaInput
• type HandleRescanInput
• type HistoryLogInput
• type HistorySummary
• type LsPage
• type MediaPatchRequest
• type MediaRequest
• type MediaUpdateField
• type MoveContext
• type PreviewSummary
• type ProcessExistingInput
• type RecursiveFileContext
• type RecursiveWalkOpts
• type RemoveStaleInput
• type ScanContext
• type ScanLoopConfig
• type ScanOutputOpts
• type ScanServiceConfig
• type ScanStats
• type ScopeFilter
  • func ConfirmCwdScope(scanner *bufio.Scanner, f ScopeFilter, verb string) (ScopeFilter, bool)
  • func ConfirmCwdScopeWithPreview(scanner *bufio.Scanner, f ScopeFilter, verb string, ...) (ScopeFilter, bool)
  • func (f ScopeFilter) HasGlobs() bool
• type ScopePreviewFn
• type StatsCounts
• type SuggestCollector
• type SuggestTypeInput
• type ThumbnailInput
• type TrackMoveInput
• type TrackScanResult
• type UniqueFilter
• type WalkEntryInput
• type WatchState

Constants

const (
	// ExitOK is the implicit zero-exit success path. Returned when the
	// operation completed with at least one row applied OR when the user
	// asked for a read-only listing that succeeded.
	ExitOK = 0

	// ExitGenericError covers DB open failures, filesystem errors during
	// rename/delete, malformed snapshots — anything the user can't fix
	// by retrying with a different prompt answer.
	ExitGenericError = 2

	// ExitScopeRejected is returned when the user explicitly answered "n"
	// (or anything that wasn't yes/global/list) at the cwd-scope
	// confirmation prompt. Distinguishable in CI from per-row decline.
	ExitScopeRejected = 10

	// ExitRowDeclined is returned when the user proceeded past the scope
	// prompt but said "n" at the per-row "Undo this? [y/N]" prompt.
	// Also used when the scanner returned EOF mid-prompt (which scripts
	// often hit when piping commands).
	ExitRowDeclined = 11

	// ExitNothingMatched is returned when the filter dropped everything
	// (no row in scope to act on). Useful for CI loops that want to
	// short-circuit instead of treating "no work" as success.
	ExitNothingMatched = 20
)

Functions

func ActionInScope

func ActionInScope(a db.ActionRecord, scope string) bool

ActionInScope inspects the snapshot JSON for any path field that lives under scope. We do NOT rely on a typed struct because different actions emit different snapshot shapes (compact uses original_path/compact_path, scan uses file_path inside Media, etc.).

func ActionMatchesGlobs

func ActionMatchesGlobs(a db.ActionRecord, f ScopeFilter) bool

ActionMatchesGlobs applies include/exclude globs to an action record.

func Execute

func Execute()

Execute is called by main.go. It is the single public entry point.

func FilterActions

func FilterActions(actions []db.ActionRecord, scope string) []db.ActionRecord

FilterActions returns only the actions touching scope (any-path rule).

func FilterActionsWith

func FilterActionsWith(actions []db.ActionRecord, f ScopeFilter) []db.ActionRecord

FilterActionsWith applies dir scope + globs in one pass.

func FilterMoves

func FilterMoves(moves []db.MoveRecord, scope string) []db.MoveRecord

FilterMoves returns only the moves rooted under scope.

func FilterMovesWith

func FilterMovesWith(moves []db.MoveRecord, f ScopeFilter) []db.MoveRecord

FilterMovesWith applies dir scope + globs in one pass.

func MoveFile

func MoveFile(src, dst string) error

MoveFile moves a file from src to dst using os.Rename with cross-device fallback.

func MoveInScope

func MoveInScope(m db.MoveRecord, scope string) bool

MoveInScope returns true when either side of the move touches scope.

func MoveMatchesGlobs

func MoveMatchesGlobs(m db.MoveRecord, f ScopeFilter) bool

MoveMatchesGlobs applies include/exclude globs to a move record.

func MustResolveTargetDir

func MustResolveTargetDir(args []string, home string) string

MustResolveTargetDir is a thin wrapper that logs the error via the caller's preferred error handler and returns "" only when the underlying resolution truly failed. The empty-return case here means a real OS error occurred (Getwd failed) — NOT a silent prompt cancellation.

Callers should treat "" as a hard failure and return immediately after logging via errlog.

func ResolveTargetDir

func ResolveTargetDir(args []string, home string) (string, error)

ResolveTargetDir is the canonical entry point for resolving a directory argument across every cobra command in this package.

home is passed in (rather than computed inside) so callers can reuse the same value they already obtained via os.UserHomeDir() — and so unit tests can inject a fake home directory.

Types

type AppendUniqueInput

type AppendUniqueInput struct {
	DiscErr error
	Filter  UniqueFilter
	Results []tmdb.SearchResult
}

AppendUniqueInput groups parameters for appending unique search results.

type BatchMovePreview

type BatchMovePreview struct {
	SourceDir string
	MoviesDir string
	TVDir     string
	Files     []os.FileInfo
}

BatchMovePreview groups parameters for batch move preview generation.

type CleanupContext

type CleanupContext struct {
	Scanner  *bufio.Scanner
	Database *db.DB
	BatchID  string
}

CleanupContext groups parameters for popout folder cleanup operations.

type DiscoverGenreInput

type DiscoverGenreInput struct {
	MediaType string
	TypeName  string
	Sorted    []genreCount
}

DiscoverGenreInput groups parameters for genre-based discovery in suggestions.

type DryRunCounters

type DryRunCounters struct {
	TotalFiles *int
	MovieCount *int
	TVCount    *int
}

DryRunCounters groups counter pointers for dry-run scan output.

type DryRunInput

type DryRunInput struct {
	VideoFiles []videoFile
	UseJson    bool
	UseTable   bool
}

DryRunInput groups parameters for dry-run scan processing.

type DryRunOutput

type DryRunOutput struct {
	JsonItems  *[]scanJsonItem
	TotalFiles *int
	MovieCount *int
	TVCount    *int
}

DryRunOutput groups mutable output pointers for dry-run scan results.

type FillRecoInput

type FillRecoInput struct {
	Database  *db.DB
	MediaType string
}

FillRecoInput groups parameters for recommendation-based suggestion filling.

type FinalizeScanInput

type FinalizeScanInput struct {
	Database  *db.DB
	ScanDir   string
	OutputDir string
	Creds     tmdbCredentials
	JsonItems []scanJsonItem
	Removed   int
	UseJson   bool
}

FinalizeScanInput groups parameters for post-scan finalization.

type FindMoveMediaInput

type FindMoveMediaInput struct {
	SrcPath  string
	DestPath string
	FileInfo os.FileInfo
	Database *db.DB
	Result   cleaner.Result
}

FindMoveMediaInput groups parameters for finding or creating media during moves.

type HandleRescanInput

type HandleRescanInput struct {
	Client   *tmdb.Client
	Database *db.DB
	EM       *db.Media
	BatchID  string
	Opts     ScanOutputOpts
}

HandleRescanInput groups parameters for rescanning a media entry.

type HistoryLogInput

type HistoryLogInput struct {
	BasePath string
	Title    string
	FromPath string
	ToPath   string
	Year     int
}

HistoryLogInput groups parameters for saving move history to JSON log.

type HistorySummary

type HistorySummary struct {
	Verb     string // "Undo" or "Redo"
	Matched  int    // rows passing the filter
	Executed int    // rows actually applied
	Failed   int    // rows that failed during execution
	Skipped  int    // rows dropped by dir/glob filter
}

HistorySummary captures the counters reported at the end of an undo/redo run. Verb is "Undo" or "Redo" — used in the banner.

type LsPage

type LsPage struct {
	Offset   int
	PageSize int
	Total    int
}

LsPage groups pagination parameters for list display.

type MediaPatchRequest

type MediaPatchRequest struct {
	Writer   http.ResponseWriter
	Request  *http.Request
	Database *db.DB
	ID       int64
}

MediaPatchRequest groups parameters for media PATCH REST handlers.

type MediaRequest

type MediaRequest struct {
	Database *db.DB
	ID       int64
}

MediaRequest groups database context for REST media handlers.

type MediaUpdateField

type MediaUpdateField struct {
	Val      interface{}
	Database *db.DB
	Key      string
	ID       int64
}

MediaUpdateField groups parameters for a single media field update.

type MoveContext

type MoveContext struct {
	Database  *db.DB
	Scanner   *bufio.Scanner
	SourceDir string
	Home      string
	Files     []os.FileInfo
}

MoveContext groups parameters for batch and interactive move flows.

type PreviewSummary

type PreviewSummary struct {
	Verb            string // "Undo" or "Redo"
	AlreadyDoneHint string // optional copy: "already reverted" / "not reverted yet"
	MatchedMoves    int    // moves passing filter and still actionable
	MatchedActions  int    // actions passing filter and still actionable
	SkippedMoves    int    // moves dropped by filter
	SkippedActions  int    // actions dropped by filter
}

PreviewSummary is the structured counter block shown by `--list` (movie undo --list / movie redo --list). It is intentionally separate from HistorySummary because preview output should never advertise "executed: 0" / "failed: 0" — nothing was applied.

Verb is "Undo" or "Redo" (not "(preview)" — printPreviewSummary adds the suffix itself so callers can't drift from the convention).

All three "matched" columns are scoped + glob-filtered counts of rows the user could act on right now. The "skipped" columns are rows that exist in the underlying history but were dropped by the dir scope or `--include` / `--exclude` patterns.

type ProcessExistingInput

type ProcessExistingInput struct {
	Client   *tmdb.Client
	Database *db.DB
	EM       *db.Media
	BatchID  string
	VF       videoFile
	Opts     ScanOutputOpts
	HasTMDb  bool
}

ProcessExistingInput groups parameters for processing existing media during scan.

type RecursiveFileContext

type RecursiveFileContext struct {
	Files   *[]videoFile
	Entry   os.DirEntry
	Path    string
	ScanDir string
	Opts    RecursiveWalkOpts
}

RecursiveFileContext groups parameters for handling a file during recursive directory walks.

type RecursiveWalkOpts

type RecursiveWalkOpts struct {
	BaseParts int
	MaxDepth  int
}

RecursiveWalkOpts groups depth-control parameters for recursive directory walks.

type RemoveStaleInput

type RemoveStaleInput struct {
	DiskPaths     map[string]bool
	Database      *db.DB
	BatchID       string
	ExistingMedia []db.Media
	Opts          ScanOutputOpts
}

RemoveStaleInput groups parameters for stale entry removal during scan.

type ScanContext

type ScanContext struct {
	Database     *db.DB
	Client       *tmdb.Client
	OutputDir    string
	BatchID      string
	ScannedItems []db.Media
	TotalFiles   int
	MovieCount   int
	TVCount      int
	Skipped      int
	HasTMDb      bool
	UseTable     bool
}

ScanContext holds shared state for a scan session.

type ScanLoopConfig

type ScanLoopConfig struct {
	Client    *tmdb.Client
	JsonItems *[]scanJsonItem
	ScanDir   string
	BatchID   string
	UseJson   bool
	UseTable  bool
	HasTMDb   bool
}

ScanLoopConfig groups parameters for the main scan processing loop.

type ScanOutputOpts

type ScanOutputOpts struct {
	UseTable bool
	UseJson  bool
}

ScanOutputOpts groups output format flags used during scan processing.

type ScanServiceConfig

type ScanServiceConfig struct {
	ScanDir   string
	OutputDir string
	Database  *db.DB
	Creds     tmdbCredentials
}

ScanServiceConfig groups parameters for post-scan services (REST, watch).

type ScanStats

type ScanStats struct {
	ScanDir   string
	OutputDir string
	Items     []db.Media
	Total     int
	Movies    int
	TV        int
	Skipped   int
	Removed   int
}

ScanStats holds aggregate counts for scan output functions.

type ScopeFilter

type ScopeFilter struct {
	Dir      string   // normalized scope dir ("" → no dir filter / --global)
	Includes []string // glob patterns
	Excludes []string // glob patterns
	// UserProvidedPath is true when the user passed an explicit [path]
	// positional argument or --global. False means the scope was inferred
	// from cwd, in which case interactive flows should confirm with the
	// user before acting.
	UserProvidedPath bool
	// AssumeYes is true when the user passed --yes / -y / --assume-yes.
	// It bypasses BOTH the cwd-scope confirmation prompt AND the per-row
	// "Undo this? [y/N]" prompt — designed for scripted runs.
	AssumeYes bool
}

ScopeFilter bundles the directory scope plus optional include/exclude glob patterns. All matchers operate on any string path field stored on the action / move record (same any-path rule used by ActionInScope).

Semantics:

• Includes empty → no include constraint (everything passes the include phase). Otherwise at least one path on the record must match at least one include pattern.
• Excludes empty → no exclude constraint. Otherwise the record is dropped if ANY of its paths matches ANY exclude pattern.
• Excludes are evaluated AFTER includes, so excludes always win.

Glob syntax is filepath.Match (POSIX shell style: *, ?, [class]). Patterns are matched against:

1. the full path (e.g. "/movies/2024/Inception/*.mkv")
2. the basename (e.g. "*.srt")
3. the basename of every parent directory (e.g. "Trash")

This makes both "*.mkv" and "Inception" useful without the user having to know which form ended up in the snapshot.

func ConfirmCwdScope

func ConfirmCwdScope(scanner *bufio.Scanner, f ScopeFilter, verb string) (ScopeFilter, bool)

func ConfirmCwdScopeWithPreview

func ConfirmCwdScopeWithPreview(scanner *bufio.Scanner, f ScopeFilter, verb string, previewCounts ScopePreviewFn) (ScopeFilter, bool)

ConfirmCwdScopeWithPreview is the richer form used by the cobra handlers — it can show a live "would act on N moves / N actions" estimate before the user confirms. ConfirmCwdScope wraps it with a nil callback for callers that don't have DB access.

func (ScopeFilter) HasGlobs

func (f ScopeFilter) HasGlobs() bool

HasGlobs reports whether any include or exclude pattern is set.

type ScopePreviewFn

type ScopePreviewFn func(ScopeFilter) (matchedMoves, matchedActions int)

ConfirmCwdScope asks the user to confirm an inferred cwd scope before running a destructive history operation. It is a no-op (returns the original filter, true) when:

• the user already passed an explicit path argument
• the user passed --global
• the scope dir is empty (== global) for any other reason

When the scope WAS inferred from cwd, the user can:

[Enter] / y → proceed with the cwd scope
g          → switch to --global (returns a global filter, true)
n / q      → cancel (returns _, false)
l          → re-print the scope details (handy after scrolling)

The verb is "Undo" or "Redo" — used purely for the prompt copy.

previewCounts is an optional callback that, given the current filter, returns (matchedMoves, matchedActions). When non-nil and at least one of the counts is > 0, the prompt also shows a "would act on" line so the user can sanity-check the filter before committing. Pass nil to suppress (e.g. for tests or non-interactive contexts).

type StatsCounts

type StatsCounts struct {
	Movies int
	TV     int
	Total  int
}

StatsCounts groups the three media count values for stats rendering.

type SuggestCollector

type SuggestCollector struct {
	ExistingIDs map[int]bool
	Client      *tmdb.Client
	Count       int
}

SuggestCollector groups parameters for suggestion collection helpers.

type SuggestTypeInput

type SuggestTypeInput struct {
	Database  *db.DB
	Client    *tmdb.Client
	MediaType string
	Count     int
}

SuggestTypeInput groups parameters for type-based suggestion generation.

type ThumbnailInput

type ThumbnailInput struct {
	Client     *tmdb.Client
	Database   *db.DB
	Media      *db.Media
	PosterPath string
	OutputDir  string
}

ThumbnailInput groups parameters for poster/thumbnail download functions.

type TrackMoveInput

type TrackMoveInput struct {
	SrcPath   string
	DestPath  string
	CleanName string
	FileInfo  os.FileInfo
	Database  *db.DB
	Result    cleaner.Result
}

TrackMoveInput groups parameters for recording a file move operation.

type TrackScanResult

type TrackScanResult struct {
	InsertErr error
	Media     *db.Media
	FullPath  string
	MediaID   int64
}

TrackScanResult groups the result of scanning a single file for action tracking.

type UniqueFilter

type UniqueFilter struct {
	ExistingIDs map[int]bool
	Count       int
}

UniqueFilter groups parameters for deduplicating search results.

type WalkEntryInput

type WalkEntryInput struct {
	Info     os.FileInfo
	Items    *[]popoutItem
	RootDir  string
	Path     string
	MaxDepth int
}

WalkEntryInput groups parameters for processing a single walk entry during popout discovery.

type WatchState

type WatchState struct {
	Seen    map[string]bool
	Client  *tmdb.Client
	HasTMDb bool
}

WatchState groups mutable state for watch-mode polling cycles.