@ssebastien/tcmd 0.1.4 → 0.1.7

package/README.md

@@ -15,29 +15,68 @@ TinyCommand `tcmd` is a midnight-commander-like CLI and desktop tool:
   the two-pane commander (the left is the source, the right the destination),
   with `t` toggling between the two views. Clicking any column, preview
   included, gives it the focus.
-- Named bookmarks: `b` records the cursor entry (or the pane directory) under
-  a name defaulting to its basename, remembering whether it is a file or a
-  directory; `g` opens a fzf-style picker over bookmark names and paths. A
-  directory bookmark opens to show its contents, a file bookmark is selected
-  and previewed in its directory.
-- Operations over the current panes: copy, move, delete/erase, stat, touch,
-  selection buffers, edit/view/open and shell commands
+- Named bookmarks: `b` opens one bookmarks panel. Type to filter the stored
+  bookmarks by name or path; when the filter is empty and the cursor entry (or
+  the pane directory) is not bookmarked yet, a first row adds it under a
+  basename-derived name. `Enter` opens the selected bookmark, `⌫`/`Delete`
+  removes it. A directory bookmark opens to show its contents, a file bookmark
+  is selected and previewed in its directory.
+- Undo/redo (`⌃Z` / `⌃⇧Z` or `⌃Y`) over recorded filesystem changes (mkdir,
+  copies to new destinations, move, rename, trashed delete), with a history list
+  (`u`); a delete reports the trash directory it used and can be undone or
+  restored from the trash browser
+  (`⇧T`), which lists trashed entries by their original path. A double click on
+  a row opens it like `Enter`.
+- Operations over the current panes: copy, move, mkdir/new, hardlink/symlink,
+  chmod/chown, delete/erase/unlink, stat, du/df, touch, selection buffers,
+  edit/view/open and shell commands; `abspath` and `realpath` show
+  copy-pasteable absolute paths and copy them to the clipboard, with the latter
+  following symlinks. `unlink` removes links only, never their targets.
 - Command panel (`:`), the one entry point, a two-pane palette: the left pane
-  filters (`:xxx`) over the CLI operations (copy, move, rename, delete… — the
-  internal TinyCmd actions live on their own keys, not the panel). The right
-  pane lists the selected command's arguments under its name — each row an
-  aligned label and its value in a boxed field (a text field to fill in), or a
-  checkbox (multiple) / radio (single) list of the selected paths wrapped in its
-  own border, with a lone path shown read-only — and the resolved command at its
-  foot. `Tab` cycles the filter and the argument rows; `Enter` runs a complete
-  command or jumps to the next missing argument. `!` lands straight on the shell
+  filters (`:xxx`) over CLI operations grouped by purpose: **Command**,
+  **File**, **Info**, **Create**, **Edit** (amber), and **Delete** (red). The
+  Command group also has the workspace-view toggle and Quit; File's `view`
+  previews the selected path; Info holds `stat`, `du` and `df`; amber Edit also
+  holds `copy` and the metadata changes. Bold section
+  titles head indented command names, alphabetized within each category. The right
+  pane lists the selected command's arguments under its name — editable values
+  use filled fields, while read-only values are plain and muted; `new`/`mkdir`
+  show the current `PATH` above a `NAME`, and `chmod`/`chown` list `PATH`
+  first. Selections use
+  a checkbox (multiple) / radio (single)
+  list of the selected paths wrapped in its own border, with a lone path shown
+  read-only. `chmod`'s `MODE` is a compact u/g/o grid of clickable R/W/X cells
+  (arrow keys move between cells, Space toggles), seeded from the selected
+  file's current mode. Labels and values sit one space in from the pane border
+  (` PATH`, ` [value]`), and `[Run]` follows the last field after a
+  blank line, aligned left in the command category's color. Amber (Edit) and
+  red (Delete) actions take two steps: the first Run turns the action into
+  `[Confirm]` and prints the command below it in the risk colour, the second
+  executes. A failed run shows `[Retry]` with a framed error block below it,
+  while a
+  successful result briefly replaces the command bar at the bottom. A selection
+  argument draws from the *focused* column, so in the explorer focusing the parent mirror
+  selects the directory under its cursor. `Tab` cycles the filter, arguments and
+  Run button; `Enter` runs a complete command or jumps to the next missing
+  argument, and a `[Close Esc]` close button sits in the dialog's top border,
+  upper right. `!` lands straight on the shell
   command. A destination/path argument browses the filesystem in a file picker
-  (`⌃O`): explorer mode has no destination pane, so a move or copy there asks
-  where to. A `rename` operation replaces a literal `FIND` with `REPLACE` across
-  the selection — one file replaces its whole name — previewing each
-  `old → new` before it runs.
+  (`⌃O`): its path is editable as a string, the matching entries sit below and
+  render like a file panel (icons, aligned sizes, scrollbar), with `..` pinned
+  at the top. Explorer mode has no destination pane, so a move or copy there
+  asks where to. A `replace` operation replaces a literal `FIND` with `REPLACE`
+  across the selection — one file replaces its whole name — previewing each
+  `old → new` mapping before it runs. Exact `rename FROM TO PATH` renames one named
+  child inside `PATH`.
 - Keyboard and mouse navigation, inline file previews — a previewed directory
-  renders as a pane (its breadcrumbs over its own listing), in both views
+  renders as a pane (its breadcrumbs over its own listing), in both views, a
+  source file highlights with tree-sitter (JavaScript, TypeScript, Markdown and
+  Zig today) through the same `code` renderable, and an image draws in place
+  through the terminal's graphics protocol (Kitty/sixel, half-block fallback),
+  the metadata card staying for formats with no decoder. `.gz` and `.bz2`
+  entries preview their decompressed contents: the inner name drives the kind
+  and highlighter (`notes.txt.gz` heads as `<GZ · TXT>`), and a body that
+  decompresses to binary stays a card
 - Symlinks are shown *and* followed: a link row prints `name -> target`
   (`notes.md -> notes.txt`, `docs/ -> ../shared`), a link to a directory is a
   directory (it sorts, opens and previews as one), and the preview reads
@@ -67,47 +106,61 @@ bun run tcmd         # open cwd (left) and ~ (right)
 bun run tcmd /tmp ~  # open specific directories
 ```
 
-Keys: `↑/↓` move (`^↑/^↓` jump a few lines), `Enter/→` open (re-entering a
-directory restores the cursor it was left with), `←/Bksp` parent (the cursor
+Keys: `↑/↓` move (`^↑/^↓` jump a few lines), `Enter/→` open (a directory
+re-opens with the cursor it was left with, a text file opens in `$EDITOR`, and
+anything that cannot be edited — an image, media, a binary, or any file on a
+host with no editor — opens the fullscreen viewer), `←/Bksp` parent (the cursor
 lands on the directory you left), `Esc`/`⇧Esc` history back/forward, `Tab`/`⇧Tab` switch panes
 (`⇧Tab` goes back), `t` toggle the commander/explorer view, `Space` mark, `b`
-bookmark the cursor entry (or the pane
-directory) under a basename-defaulted name, `g` jump to a bookmark, `:` open the
-command panel (the one entry point: CLI operations and TinyCmd actions, their
-arguments, the live resolved command, and the inline file picker on `⌃O`), `v` preview (fullscreen viewer when
+open the bookmarks panel (filter, add the current path, `Enter` open,
+`⌫`/`Del` remove), `:` open the
+command panel (the one entry point for CLI operations, grouped by risk with
+editable arguments, an explicit Run button and the inline file picker on `⌃O`),
+`v` preview (fullscreen viewer when
 the terminal is narrow), `⇧V` maximize the preview over the columns and back
-again, `O`/`E` open/edit the previewed file, `/` fuzzy-filter
+again (in either full view, `↑`/`↓` scroll a file preview and `←`/`→` step to
+the previous/next entry), `O`/`E` open/edit the previewed file, `/` fuzzy-filter
 the active pane (`Enter` keeps it, `Esc` clears), `!` open the panel on the
-shell command, `^R` reload, `?` key reference, `q` quit.
+shell command, `F5`/`r`/`^R` reload, `?` key reference, `q` quit.
+
+Listings refresh themselves when the filesystem changes: the TUI and desktop
+views watch the displayed directories natively, while the web view polls them
+every few seconds. Hidden columns pause their watcher and re-read when shown.
+A refresh keeps the selected entry selected, so files written by other
+programs appear without moving the cursor. The keys above (and the web toolbar
+button) remain for a forced re-read.
 
 The workspace opens in explorer mode with a slim identity bar (`TinyCmd -
 HOST`) — the view mode and version trailing at its right, the mode word drawn
 letter by letter along the logo's own gradients (`explorer` in the Tiny blues,
-`commander` in the Cmd oranges) and the version dim after it — over an
+`commander` in the Cmd oranges, clicking it toggles the view) and the version
+dim after it — over an
 unframed tiling of pane boxes (the two middle edges sit side by side) labelled
 **SRC** (left, source) / **DST** (right, destination) in commander, with a
 header row (label + clickable breadcrumbs — collapsed to first letters like
 `/h/s/W/Perso/tcmd` when the width demands — + the inline filter) separated by a
-rule from the listing, an entry-detail line for the selected entry, and one
-summary row, so the columns stay aligned. The detail line shows
+rule from the listing, and an entry-detail line for the selected entry. The
+detail line shows
 `date · type · size · rights` with the rights right-aligned, the date and size
-bright, and the size/rights dropping out when the pane is too narrow; the
-summary row is indented to match. The active pane's border and header
-rule are highlighted and its cursor row uses the strong cursor colour, while
-the inactive pane stays dim with a muted cursor. Rows lead with a yazi-style
+bright, and the size/rights dropping out when the pane is too narrow. The active
+pane's border and header rule take the view mode's colour — the Tiny blue in
+explorer, the gold accent in commander — and its cursor row uses the strong
+cursor colour, while
+the inactive pane stays dim with a muted cursor. TUI rows lead with a yazi-style
 Nerd Font icon (folder/link kind icons plus a per-extension icon, `Makefile`,
-`Dockerfile` and dotfiles included), on unless `TCMD_ICONS=0` — it needs a
-Nerd-Font-patched terminal font, and the web view never shows icons. The
-command panel marks its entries the same way — a glyph in the TUI, a `cli`/`app`
-tag on the web. A
+`Dockerfile` and dotfiles included), on unless `TCMD_ICONS=0`; it needs a
+Nerd-Font-patched terminal font. The web and desktop views use local Lucide SVG
+icons for toolbar actions, file kinds, bookmarks, and Help key badges; command
+panel entries show a chevron to indicate their argument pane. A
 context-aware inspector sits
 on the right when the terminal is at least 100 columns wide, and becomes a
 fullscreen viewer below that; `⇧V` expands it over the whole pane row —
 parent and current included — and brings the previous layout back on the next
-press. The status bar lists every binding as a bracket
-shorthand (`[Open ⏎]`) wrapping over as many rows as the width demands — the
-marked count trails the list, and a notice or error swaps the keys for a
-one-line status. Below 64×16
+press. The status bar keeps its fixed bracket shorthands on one line
+(`[Commands :]`, `[Mark Spc]`, `[Filter /]`, `[Switch ⇥]`, `[Bookmarks b]`,
+`[Toggle Mode t]`, `[Help ?]`) and elides entries behind `…` when the width
+runs out — the marked count trails the list, and a notice or error swaps the
+keys for a one-line status. Below 64×16
 the app shows a resize hint instead of the workspace.
 
 ### View modes
@@ -182,12 +235,67 @@ only supports OPFS); the server binds to loopback by default (`HOST`
 overrides it) and requires a per-process token injected into `index.html`.
 `TCMD_WEB_ROOT=/some/dir` confines the API
 (default `/`, the same access as `bun run tcmd`), but it is not a sandbox:
-don't expose the port. With OPFS, deleting moves entries to `/.trash`; the API
-uses the desktop trash. Open/edit/run are unavailable in the browser either
-way (the null host adapter reports it in the command bar); everything else —
-navigation, marks, scripting, copy/move/erase — works on either
+don't expose the port. Symlinks that resolve outside the root are rejected;
+root and destination checks are not race-proof against another local process
+changing the filesystem during a request. With OPFS, deleting moves entries to `/.trash`;
+the API uses the desktop trash. OPFS coordination across tabs uses Web Locks
+when available; without them, writes are coordinated per adapter only.
+Open/edit/run are unavailable in the browser
+either way (the null host adapter reports it in the command bar); everything
+else — navigation, marks, scripting, copy/move/erase — works on either
 backend. `public/index.html` is the host page; `public/main.js` is generated.
 
+### Desktop app (tinyjs)
+
+The native desktop target reuses the web presentation and shared session, but
+uses a tinyjs backend for real filesystem access. It runs without Bun/Node in
+the shipped app and does not start an HTTP server or open a port.
+
+Install [tinyjs](https://tinyjs.app/) and the project dependencies, then run:
+
+```sh
+bun install
+bun run desktop:dev       # bundle the webview UI, then open the native window
+bun run desktop:build     # tinyjs build; emits a platform-native app/package
+```
+
+`tinyjs.json` configures the app. `tinyjs build` bundles the desktop frontend
+through `desktop:bundle`; the source page is `desktop/frontend/index.html`.
+For frontend changes during development, rerun `bun run desktop:bundle` before
+reloading the window. The desktop uses the system webview and requires tinyjs
+0.57.0 or newer.
+
+The desktop window keeps the native title bar, hides the native menu, and uses
+an in-app toolbar for folder navigation, refresh, view/preview toggles, commands
+and help. Its toolbar replaces the TinyCmd identity header; the browser UI keeps
+that header. Press F6 to move focus between the workspace and toolbar; toolbar
+buttons use native Tab/Enter/Space keys, and Escape returns to the workspace.
+
+The web UI uses the system sans-serif font for controls and chrome, with the
+M+1Code Nerd Font Mono bundled for filenames, paths, and file content. The
+font is from Nerd Fonts v3.5.1 and is distributed under SIL OFL 1.1; its license
+is included in `public/fonts/OFL.txt`.
+The UI icons are from Lucide and distributed under ISC (with the listed Feather
+icons under MIT); the license is included in `public/licenses/LUCIDE.txt`.
+
+On Linux, the tinyjs launcher also needs the Ayatana AppIndicator runtime. On
+Fedora install it with `sudo dnf install libayatana-appindicator-gtk3`; on
+Debian/Ubuntu use `sudo apt install libayatana-appindicator3-1`. Install the
+WebKitGTK runtime required by tinyjs as well.
+
+Filesystem operations are performed by the backend using txiki.js APIs. Text
+files open in the operating system's default editor; `!` / shell commands run
+in a non-interactive shell and display captured output in a native dialog.
+Trash uses the Freedesktop trash under `$XDG_DATA_HOME` (or
+`~/.local/share/Trash`), including undo/restore. The current desktop adapter
+supports POSIX paths on Linux and macOS. Windows drive/UNC paths are not yet
+supported; the app reports this rather than attempting file operations.
+
+The desktop backend has full access to the current user's files, and the
+command panel intentionally exposes shell execution. Treat commands and
+filesystem prompts accordingly. Browser and TUI builds remain separate and
+continue to use their existing backends.
+
 ## Architecture
 
 MVC with a presentation-agnostic core, so a web UI can share the same model
@@ -204,7 +312,7 @@ src/js/tcmd/
     directory.js one pane's directory: path, entries, view, cursor, marks
     pane.js      one directory, proxying its cells + currentPane resolution
     bookmarks.js named bookmarks (path + file/dir kind) + the memory/file stores
-    panel.js     command panel: CLI ops + TinyCmd actions, args bound from context
+    panel.js     grouped CLI command panel, with arguments bound from context
     session.js   two panes + parent/preview mirrors, view mode, active pane, preview, panel, dispatch
     keymap.js    key chords -> command ids
     commands.js  command registry; commands are `run(session, payload)`
@@ -217,7 +325,7 @@ src/js/tcmd/
     FileList.js …     one `.js` per component (behaviors + pure helpers)
     FileRow.js …      row behaviors shared by both engines
     Frame.js          workspace chrome, breakpoints and command-bar geometry
-    Help.js           key-reference overlay behaviors + the grouped key text
+    Help.js           key-reference overlay behaviors + the two-column key text
     format.js         presentation helpers (sizes/counts)
   tui/      View (select.tui templates on OpenTUI)
     app.js       binds App.js + App.xml + TUI environment; size/help cells
@@ -258,8 +366,9 @@ of use.
 
 `components/Frame.js` holds the renderer-free workspace chrome (brand bar,
 responsive breakpoints, pane borders, command-bar geometry) and
-`components/Help.js` holds the key reference — behaviours and the grouped key
-text — used by both views. Web-only components live under `web/` (`header.js` +
+`components/Help.js` holds the key reference — behaviours and the two-column
+key text, with every distinct keymap chord shown in the command bar's bracket
+style — used by both views. Web-only components live under `web/` (`header.js` +
 `header.html`, plus the DOM effects in `effects.js` and the bookmark store in
 `bookmarks.js`). Shared
 behaviors only ever grow additively (a new key for a new presentation),
@@ -288,8 +397,8 @@ Decoupling rules:
   see `src/js/tcmd/vendor/`)
 - Bun as the runtime
 
-`deps/` symlinks to sibling checkouts; `scripts/link-deps.sh` (run as
-postinstall) re-links `node_modules` so upstream edits propagate.
+`deps/` symlinks to sibling checkouts; run `scripts/link-deps.sh` after
+`bun install` to re-link `node_modules` so upstream edits propagate.
 
 ## Tests
 
@@ -307,12 +416,14 @@ tests run the shared logic through select.js on a happy-dom document.
       bar, command panel, text preview
 - [x] File operations (copy/move/delete/erase/stat/touch/sel), with the
       `$A`/`$B` pane filesets and `$FILE` still resolving in any argument
-- [x] Unified command panel (`:`): the CLI operations and the TinyCmd actions in
-      one filtered list, each marked by its namespace, with editable arguments
-      and a resolved-command preview; `!` lands on the shell command
+- [x] Grouped command panel (`:`): white / amber / red risk sections, editable
+      arguments, an explicit Run action and an inline picker; `!` lands on shell
 - [x] Pane fuzzy filtering (`/` to filter, `Enter` to keep, `Esc` to clear)
-- [x] Named bookmarks (`b` records, `g` jumps, persisted to a JSON file)
+- [x] Named bookmarks (`b` opens the panel to add, filter, open or remove them,
+      persisted to a JSON file)
 - [ ] Quick find, grep
-- [ ] Image/PDF/audio/video previews
+- [x] Image previews (terminal graphics protocol) and tree-sitter source
+      highlighting in the inspector
+- [ ] PDF/audio/video previews
 - [x] Web view on the same core (shared components rendered by select.js)
 - [x] Pane navigation history (`Esc`/`⇧Esc` back/forward)

package/desktop/dist/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>TinyCommand</title>
+		<link rel="stylesheet" href="./style.css" />
+	</head>
+	<body>
+		<div id="app"></div>
+		<script type="module" src="./main.js"></script>
+	</body>
+</html>