PHPackages sugarcraft/candy-files - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [CLI & Console](/categories/cli) 4. / 5. sugarcraft/candy-files ActiveProject[CLI & Console](/categories/cli) sugarcraft/candy-files ====================== Dual-pane terminal file manager built on the SugarCraft stack. Inspired by superfile and Midnight Commander. Navigate two directories side-by-side, sort by name / mtime / size, multi-select, delete with confirmation, swap focus with Tab. 20PHP Since Jun 22Pushed 5d agoCompare [ Source](https://github.com/sugarcraft/candy-files)[ Packagist](https://packagist.org/packages/sugarcraft/candy-files)[ RSS](/packages/sugarcraft-candy-files/feed)WikiDiscussions master Synced today READMEChangelogDependenciesVersions (1)Used By (0) [![candy-files](.assets/icon.png)](.assets/icon.png) CandyFiles ========== [](#candyfiles) [![CI](https://github.com/detain/sugarcraft/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/detain/sugarcraft/actions/workflows/ci.yml)[![codecov](https://camo.githubusercontent.com/d81dab63b60311a311002ccba69781e26919d63673c633b18f7b919650f40e19/68747470733a2f2f636f6465636f762e696f2f67682f64657461696e2f737567617263726166742f6272616e63682f6d61737465722f67726170682f62616467652e7376673f666c61673d63616e64792d66696c6573)](https://app.codecov.io/gh/detain/sugarcraft?flags%5B0%5D=candy-files)[![Packagist Version](https://camo.githubusercontent.com/e3f2146e47b910089c9f9692bec9606be2346f7134f496781e3313499cf6be5f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f737567617263726166742f63616e64792d66696c65733f6c6162656c3d7061636b6167697374)](https://packagist.org/packages/sugarcraft/candy-files)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP](https://camo.githubusercontent.com/e78ffc83837c0d12647811a7fd1910c3cbeae04988de94bb4fd5b67e0874696a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d254532253839254135382e312d3838393262662e737667)](https://www.php.net/) [![demo](.vhs/navigate.gif)](.vhs/navigate.gif) Dual-pane terminal file manager built on the SugarCraft stack — port of [`yorukot/superfile`](https://github.com/yorukot/superfile), with the Midnight Commander look. ``` ┌────────────────────────────────────┐ ┌────────────────────────────────────┐ │ /home/alice [name-asc] │ │ /var/log [mtime-desc] │ │ ────────────────── │ │ ────────────────── │ │ ▸ ../ DIR │ │ ../ DIR │ │ Documents/ DIR │ │ ▸✓ syslog 240KB │ │ Downloads/ DIR │ │ auth.log 12KB │ │ .config/ DIR │ │ Xorg.0.log 4.0KB │ │ notes.md 12KB │ │ │ │ todo.txt 512B │ │ │ └────────────────────────────────────┘ └────────────────────────────────────┘ Tab swap · ↑↓ jk move · Enter open · ← h up · space select · s sort · . hidden · d delete · r refresh · q quit · / search · t tabs · u undo ``` Run it ------ [](#run-it) ``` composer install ./bin/candyfiles [LEFT_DIR] [RIGHT_DIR] ``` Default: left pane = current directory, right pane = `$HOME`. Keys ---- [](#keys) KeyAction`Tab`Swap focus between panes`↑` / `k`Move cursor up`↓` / `j`Move cursor down`Home` / `g`Top of listing`End` / `G`Bottom of listing`Enter` / `→`Open directory (or no-op on a file)`←` / `h`Go up one directory`Space`Toggle selection on the entry under cursor + advance`s`Cycle sort order (name → mtime → size, asc / desc)`.`Toggle hidden-file visibility`c`Copy (selection or cursor) to inactive pane; `y` confirm`m`Move (selection or cursor) to inactive pane; `y` confirm`R`Rename (cursor entry); new name prompted; `y` confirm`d`Delete (selection or cursor); requires `y` confirm`r`Refresh active pane`q`Quit`/`Start search mode; type to filter; Enter to open`Escape`Exit search mode`t`Duplicate current tab`Ctrl+w`Close current tab`Ctrl+Tab`Cycle to next tab`Ctrl+Shift+Tab`Cycle to previous tab`u` / `Ctrl+z`Undo last operationArchitecture ------------ [](#architecture) The whole transition layer is pure — filesystem I/O is injected as a `Closure(string $path): list` so every transition is unit-testable without tmp dirs or stat fixtures. FileRole`Entry`Value object: name, isDir, size, mtime, isLink, isHidden`Sort`Enum (NameAsc/NameDesc/MtimeAsc/MtimeDesc/SizeAsc/SizeDesc) + comparator`Pane`One pane: cwd, entries, cursor, selection set, sort, showHidden`ConfirmState`Pending-confirmation enum (None / DeleteSelected)`Manager`SugarCraft Model — orchestrates two panes, handles all keys + confirm gate`FsLister`Default lister: `scandir` + `lstat` against the live filesystem`Renderer`Pure view function — two pane boxes side-by-side + status line`BulkRename`Bulk rename engine: regex template + sequential {n}/{name}/{ext} placeholders`PreviewPane`File preview: ANSI image render via Mosaic for images, metadata block otherwise`AsyncOps`Async copy/move/rename via React\\Promise — keeps TUI responsive during I/OTest plan --------- [](#test-plan) - 36 tests / 65 assertions - Pure-state coverage: `Entry` (size formatting, parent sentinel), `Sort` (every order × dirs-first × cycle), `Pane` (open / navigate / move / select / sort / hidden toggle / parent-path / join) - `Manager` integration: Tab swap, key dispatch per pane, confirm gate (`d` arms, `y` confirms, anything else cancels), refresh status Demos ----- [](#demos) ### Navigation [](#navigation) [![navigate](.vhs/navigate.gif)](.vhs/navigate.gif) ### Search [](#search) [![search](.vhs/search.gif)](.vhs/search.gif) ### Multi-select and delete [](#multi-select-and-delete) [![multi-select](.vhs/multi-select.gif)](.vhs/multi-select.gif) ### Tab management [](#tab-management) [![tabs](.vhs/tabs.gif)](.vhs/tabs.gif) ### Sort cycling [](#sort-cycling) [![sort-cycle](.vhs/sort-cycle.gif)](.vhs/sort-cycle.gif) ### Undo delete [](#undo-delete) [![undo](.vhs/undo.gif)](.vhs/undo.gif) ### Hidden-file toggle [](#hidden-file-toggle) [![hidden-files](.vhs/hidden-files.gif)](.vhs/hidden-files.gif) Constructing Manager -------------------- [](#constructing-manager) `Manager` has 15 constructor parameters. Use the fluent builder for readability and to avoid parameter-order mistakes: ``` $manager = Manager::builder() ->withLeft($leftPane) ->withRight($rightPane) ->withActiveIdx(0) ->withStatus('') ->withConfirm(ConfirmState::None) ->withLister(fn(string $path): list => FsLister::lister()($path)) ->withSearchQuery(null) ->withSearchResults([]) ->withSearchCursor(0) ->withTabs([]) ->withTabIndex(0) ->withShowTabBar(false) ->withUndoStack([]) ->withRedoStack([]) ->withPendingOpDest(null) ->withPendingOpType(null) ->build(); ``` The direct constructor is kept for backward compatibility only — new code should use `Manager::builder()`. Status ------ [](#status) Phase 10 entry — copy / move / rename / undo are wired. Three-phase confirm gate (`c`/`m`/`R` arms, `y` confirms, anything else cancels). Undo restores delete/move/rename; copy undo is informational (original preserved). Everything underneath (the pure-state transition layer) is already in place. ### Health Score 21 — LowBetter than 18% of packages Maintenance65 Regular maintenance activity Popularity3 Limited adoption so far Community6 Small or concentrated contributor base Maturity11 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/b1036e0717211b8030b83cbe729e8ba6ba442fdbd5285fb97a39d7dcfe339342?d=identicon)[detain](/maintainers/detain) --- Top Contributors [![detain](https://avatars.githubusercontent.com/u/1364504?v=4)](https://github.com/detain "detain (5 commits)") --- Tags candycoredeletedirectory-navigatordual-panefile-explorerfile-managerfile-opsfilesystemkeyboard-drivenmidnight-commandermulti-selectncursesproductivitysortsupercandysuperfileterminaltuitwo-panevfs ### Embed Badge ![Health badge](/badges/sugarcraft-candy-files/health.svg) ``` [![Health](https://phpackages.com/badges/sugarcraft-candy-files/health.svg)](https://phpackages.com/packages/sugarcraft-candy-files) ``` ### Alternatives [seld/cli-prompt Allows you to prompt for user input on the command line, and optionally hide the characters they type 24726.4M22](/packages/seld-cli-prompt)[illuminate/console The Illuminate Console package. 13045.3M6.2k](/packages/illuminate-console) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)