All 22 apps

CandyFiles

Dual-pane terminal file manager

inspired by yorukot/superfile file-manager midnight-commander dual-pane

CandyFiles code coverage

Two panes side-by-side, Midnight Commander style. Tab to swap focus, multi-select, sort cycling, hidden-file toggle, delete-with-confirm. Pure-state transition layer — filesystem is injected, every transition is unit-testable.

Install

composer require sugarcraft/candy-files

While the release channel is dev-only the inline :@dev is required — Packagist carries just dev-master, and a fresh project's default stable minimum-refuses the bare command.

Quickstart

# 1. Composer consumer — the package bin (composer.json "bin"):
vendor/bin/candy-files [LEFT_DIR] [RIGHT_DIR]

# 2. Source checkout of this repo:
composer install
./bin/candy-files [LEFT_DIR] [RIGHT_DIR]

# 3. Rolling phar — published on GitHub Releases under the
#    candy-files/latest tag (with .sha256/.sig verification sidecars and
#    the .phar.commit build stamp + .phar.pins.json pin-map — quote
#    the latter pair in bug reports):
php candy-files.phar [LEFT_DIR] [RIGHT_DIR]

# Flags (answered before the positional directory scan):
#   --version  build stamp — phar-aware via Support\Version
#   --help/-h  usage
#   --print-cd cd-on-quit handshake: the interface rides /dev/tty
#              and stdout carries ONLY the final active-pane
#              directory at exit — capture it in a shell function
#              (candy-files-cd, see the README handshake section)
# A missing/unreadable start directory refuses up front with exit 1
# ("left/right directory does not exist: ").
# Default: left = cwd, right = $HOME.
# Size honesty: each pane box measures (cols - 2) / 2 cells outer — the
# name column, header clip and separator all derive from the content
# width inside it, so the composed frame lands exactly on the live
# terminal width at any size. Rows are windowed: the listing scrolls a
# window that follows the cursor (↑/↓ fold hints mark hidden head/tail),
# and the status line and confirm prompts are always on screen.

# Keys
# Tab        Swap focus
# ↑ / k      Move up
# ↓ / j      Move down
# Home / g   Top
# End / G    Bottom
# Enter / →  Open: directory navigates, archive (.zip/.tar/.tgz/.tbz2) browses read-only, file launches $EDITOR
# l          Page a file through $PAGER, or the built-in viewer when none is installed; on a dir it opens (vim-diamond right)
# o          Open with the platform default (xdg-open / open / cmd start) — argv list, never a shell string
# x          Run the entry under cursor when it carries the exec bit; inside an archive view, extract to the other pane
# ← / h      Up one directory
# Space      Toggle selection + advance
# Ctrl+a     Select every listed entry (the .. sentinel is never marked)
# v          Invert the selection — pressing it twice restores the set
# *          Pattern-select: type a glob-lite pattern (fnmatch, never regex)
# s          Cycle sort order (8 modes)
# e          Direct-select extension sort
# .          Toggle hidden files
# c          Copy selection or cursor → inactive pane (confirm: y or the locale's affirmative)
# m          Move selection or cursor → inactive pane (confirm: y or the locale's affirmative)
# R          Rename cursor entry — type new name, Enter commits, Backspace edits, Esc cancels
# N          Create directory in the active pane — same text-entry; u removes it while empty
# d          Delete (selection or cursor) — confirm gate arms first
# y / Y      Yank (copy / move) the selection or cursor entry into the yank register
# p          Paste the register into the active pane's directory (existing confirm gate)
# w / W      Copy the full path / bare name to the clipboard over OSC 52
# a          Pin the active directory as a bookmark · B opens the bookmarks overlay (Enter jumps, d unpins)
# I          Info overlay: path, type, size, permissions, owner, times, link target, free space
# r          Refresh active pane
# q          Quit (two presses while copy batches are in flight)
# ?          Help overlay — every binding one per row, Esc or ? closes
# /          Search mode — fuzzy filter by name of the active pane; arrows move the result cursor, Enter opens dirs / lands on files, Backspace-to-empty exits; Ctrl+R inside search toggles the bounded recursive walk (hits show their path relative to the pane)
# Escape     Exit search mode · cancel armed gates and text-entry · clear selection (outside modes)
# t          Duplicate current tab
# Ctrl+w     Close current tab
# Ctrl+O     Open a typed path in the active pane (~ expands, relative joins the pane cwd)
# 1-9        Switch to tab 1-9 (bare digit or Alt+n)
# Ctrl+Tab   Cycle to next tab — terminals that report modified Tab
# Ctrl+Shift+Tab  Previous tab
# Ctrl+PgUp  Next tab · Ctrl+PgDn  Previous tab — tmux/browser terminals may intercept modified Page keys
# u / Ctrl+z Undo last operation
# Ctrl+y     Redo last undo
# Mouse      Wheel scrolls the pane under the pointer · click activates + parks the cursor · Ctrl+click toggles the mark · double-click opens · tab-bar click switches tab

What's in the box

Dual panesLeft + right; Tab swaps focus. Each pane has its own cwd, cursor, selection, sort, hidden-flag.
Multi-selectSpace toggles + advances. Ctrl+a marks every listed entry, v inverts, * pattern-selects with a glob-lite prompt. Selection survives r relist and sort; leaving a directory stashes its marks and re-entering re-adopts them for names that still exist (CF-31) — the stash is keyed by directory, so a mark can never act on a same-named entry elsewhere. Escape clears.
Eight sort modesname / mtime / size / extension, asc / desc — s cycles, e jumps straight to extension (CF-46).
Hidden-file toggle. hides / shows dotfiles.
Copy / Move / Renamec/m stage to the inactive pane, y commits. R opens a text-entry rename submode — type the new name, Enter commits, Esc cancels. Undo covers delete, move and rename (copy undo is informational).
Delete-with-confirmd arms the gate, y (or the prompt's taught localized affirmative) commits — protects against fat-finger deletes. Files move to a per-session ephemeral trash (mode 0700, wiped on exit; a cross-device delete is announced PERMANENT before you confirm).
Injectable FSFsLister closure — swap for a fixture lister in unit tests with no tmp dirs.
RequirementsPHP ^8.3 with ext-intl and ext-mbstring — both hard-required transitively by sugar-core, whose cell-width math segments through ICU, so composer install is the step that refuses on a bare php-cli machine.
Live search/ fuzzy-filters the active pane's listing by name (dotfiles obey the . visibility law). Matching compares NFC-normalized names, so a composed query finds macOS's decomposed bytes and vice versa (CF-48). ↑/↓ move the result cursor, so k, j and every other printable type into the query (/ itself cannot). Enter opens a directory result; on a file result it exits search with the pane cursor landed on the hit. A Backspace that empties the query exits. Ctrl+R inside search arms a bounded recursive walk of the whole tree (CF-17) — depth, name-count, and hit budgets, with the status announcing "search partial" when any cap fires.
MouseThe launcher requests SGR cell-motion reporting: the wheel scrolls the hovered pane, a click activates it and parks the cursor, Ctrl+click toggles the mark, a double-click opens, and a tab label click switches tabs. Modal frames (confirm gate, help, info, bookmarks, search) swallow the pointer so a click can never answer a prompt (CF-55).
MetadataTerminals of 100 columns or more add a modification-time column to every pane row; I opens a stat overlay read fresh with lstat (type, bytes, drwxr-xr-x + octal, owner:group, times, link target, free space) (CF-52).
Yank / paste & clipboardy/Y stage a copy or move, p arms the ordinary confirm gate at the active pane's directory; w/W put the path or name on the clipboard over OSC 52, refusing a dumb/linux TERM and admitting the terminal may ignore the sequence (CF-32, CF-50).
Bookmarksa pins the directory, B lists the pins, Enter jumps through the typed-path door, d unpins; stored as atomic 0600 JSON under $XDG_DATA_HOME/candy-files/ (CF-30).
ArchivesEnter on a .zip, .tar, .tar.gz or .tar.bz2 browses it as a read-only directory; x extracts to the other pane through the copy gate on the event loop. Zip-slip names, links and devices are dropped, and 256 MiB scan / 512 MiB extract ceilings stop decompression bombs (CF-33).
Built-in viewer & open-with-defaultl falls back to a read-only in-app viewer (head 256 KiB, sanitized lines) when no pager exists; o opens the entry with xdg-open/open as an argv list (CF-03).
Tab managementt duplicates the current tab, Ctrl+Tab/Ctrl+Shift+Tab cycle (needs a terminal that reports modified Tab; Ctrl+PgUp/Ctrl+PgDn are the alternative — tmux and browser terminals may intercept modified Page keys), Ctrl+w closes (refuses the last tab).
Undou or Ctrl+z restores the last delete / move / rename; Ctrl+y redoes.
Localized promptsThe executable activates a language detected from $LC_ALL/$LANG (16 catalogs, English default). Confirmation gates honor the affirmative each locale's prompt teaches — a German (j/n) answers j, a Russian (д/н) answers д — and y works everywhere.

Source & demos

Try the quickstart →

Key Classes

ClassMethodDescription
Managerstart(leftCwd, rightCwd, ?lister)Factory — initializes two panes + first tab
Managerupdate(Msg): [Model, ?Cmd]Main event loop — key dispatch, confirm gate
Managerview(): stringRenders two panes + tab bar + status line
Managercopy(src, dst), move(src, dst), rename(src, newName)Direct single-entry helpers — rename/move run synchronously; the deferred engine is copy-only, and the committed copy path goes through the async command, not these
Managersearch(query), exitSearch(), openSearchResult()Live search mode
Managerundo(), redo(), canUndo(), canRedo()Delete / move / rename undo/redo stack (copy undo is informational); u/Ctrl+z undo, Ctrl+y redo
ManagerduplicateTab(), closeTab(), switchTab()Tab management
ManageropenNewTab(path)API tab push — path defaults to /; since CF-29 a key binding carries a path too: Ctrl+O opens the typed-path prompt in the active pane (t duplicates)
ManagermoveSearchCursor(delta)Result-cursor motion in search mode (clamped to the result list)
Managerbuilder(): ManagerBuilderFluent immutable construction of the eighteen founding fields — see README "Constructing Manager"
Paneopen(cwd, lister, sort, showHidden): selfFactory — reads and sorts directory
Panenavigate(lister): selfEnter directory under cursor (no-op on files)
PanetoggleSelection(): selfAdd/remove cursor entry from selection set
Sortapply(entries): list<Entry>Sort entries (parent sentinel stays at index 0)
Sortcycle(): selfCycles: name → mtime → size → extension, each asc then desc, wrapping to name-asc (CF-46)
EntrydisplaySize(): stringReturns "DIR" / "LINK" / compacted bytes

Demos.

GIFs recorded against the live app — 7 tapes under .vhs/ drive ./bin/candy-files over real directories. Regenerated automatically on every push that touches the source.

Navigate Tab-swap, multi-select, sort cycle, delete-with-confirm.
Search Type "/" to fuzzy-filter the active directory by name, arrows move the result cursor, Enter lands on the hit.
Multi-select

Multi-select

Space toggles selection, d+y deletes all selected.
Tabs

Tab management

t duplicates, Ctrl+Tab (or Ctrl+PgUp/PgDn) cycles, Ctrl+w closes.
Sort cycle

Sort cycle

s cycles through all 8 sort modes: name/mtime/size/extension × asc/desc.
Undo

Undo delete

u or Ctrl+z restores the last deleted entry.
Hidden files

Hidden-file toggle

. reveals and hides dotfiles.