@ssebastien/tcmd 0.1.4 → 0.1.7

package/src/js/tcmd/core/os.js

@@ -14,6 +14,13 @@
 // - `edit(path)`: Promise<void> - $EDITOR (or vi)
 // - `run(command, options)`: Promise<void> - `$SHELL -c command` in
 //   `options.cwd`
+// - `copy(text)`: boolean - best-effort clipboard write. The TUI sends OSC 52
+//   through the renderer; the browser and desktop webview use the Clipboard
+//   API. False when the host has no clipboard.
+// - `canEdit`: boolean - whether `edit` can launch an editor at all. A host
+//   without one (the web's null adapter) sets it false, so Enter on a file
+//   falls back to the fullscreen inspector instead of erroring (see
+//   `core/commands#pane.enter`).
 
 // `node:child_process` is imported lazily: only `createNodeOs` needs it, so
 // bundles that use the null adapter (the web view, tests) never pull in a Node
@@ -29,9 +36,14 @@ function loadChildProcess() {
 
 // Function: createNodeOs
 // Node/Bun-backed host adapter. `suspend`/`resume` are optional hooks the TUI
-// uses to release and restore the terminal around interactive commands.
-function createNodeOs({ suspend, resume } = {}) {
+// uses to release and restore the terminal around interactive commands;
+// `copy` is the TUI's OSC 52 hook (`renderer.copyToClipboardOSC52`).
+function createNodeOs({ suspend, resume, copy } = {}) {
 	return {
+		canEdit: true,
+		copy(text) {
+			return Boolean(copy?.(`${text ?? ""}`))
+		},
 		async open(path) {
 			await openWith(path, openerCandidates())
 		},
@@ -48,14 +60,28 @@ function createNodeOs({ suspend, resume } = {}) {
 	}
 }
 
+// Function: copyToBrowserClipboard
+// Best-effort clipboard write for a browser or desktop webview. The write is
+// asynchronous but fire-and-forget; a refused write (no permission, no user
+// gesture) leaves the clipboard untouched.
+function copyToBrowserClipboard(text) {
+	const clipboard = globalThis.navigator?.clipboard
+	if (!clipboard?.writeText) return false
+	void clipboard.writeText(`${text ?? ""}`).catch(() => {})
+	return true
+}
+
 // Function: createNullOs
 // Host adapter for environments without a shell (web): every operation fails
 // with a clear message, which the dispatch path reports in the command bar.
+// Clipboard access is the exception: the browser has one.
 function createNullOs() {
 	const unsupported = (name) => async () => {
 		throw new Error(`${name} is not available in this environment`)
 	}
 	return {
+		canEdit: false,
+		copy: (text) => copyToBrowserClipboard(text),
 		open: unsupported("open"),
 		edit: unsupported("edit"),
 		run: unsupported("run"),
@@ -123,6 +149,6 @@ async function runDetached(command, args) {
 	})
 }
 
-export { createNodeOs, createNullOs }
+export { copyToBrowserClipboard, createNodeOs, createNullOs }
 
 // EOF

package/src/js/tcmd/core/pane.js

@@ -51,10 +51,10 @@ function currentPane(session) {
 // await pane.refresh()
 // pane.entries.value // sorted, filtered FileEntry[]
 // ```
-function createPane({ fs, path: initialPath, context } = {}) {
+function createPane({ fs, path: initialPath, context, watch } = {}) {
 	const pane = {}
 	pane.fs = fs
-	pane.directory = createDirectory({ fs, path: initialPath, context })
+	pane.directory = createDirectory({ fs, path: initialPath, context, watch })
 
 	// Proxy cells mirror the directory, so views address the pane uniformly.
 	const dir = pane.directory
@@ -70,6 +70,7 @@ function createPane({ fs, path: initialPath, context } = {}) {
 	pane.disk = dir.disk
 	pane.segments = dir.segments
 	pane.history = dir.history
+	pane.autoRefresh = dir.autoRefresh
 
 	// Function: current
 	// The pane's directory.
@@ -79,6 +80,7 @@ function createPane({ fs, path: initialPath, context } = {}) {
 	// currentEntry / toggleMark / setFilter / clearFilter — delegate to the
 	// directory.
 	pane.refresh = () => pane.directory.refresh()
+	pane.setAutoRefresh = (enabled) => pane.directory.setAutoRefresh(enabled)
 	pane.navigate = (path, options) => pane.directory.navigate(path, options)
 	pane.up = () => pane.directory.up()
 	pane.open = () => pane.directory.open()

package/src/js/tcmd/core/panel.js

@@ -5,30 +5,35 @@
 
 // Module: tcmd/core/panel
 // The command panel (Commando): the one entry point for the CLI operations
-// (`copy`, `move`, `rename`, `delete`, `run` — the `core/operations` registry).
-// They are listed flat in one column, ranked by match importance once a query
-// filters them (see `filterPanelEntries`). The internal TinyCmd actions are not
-// listed here — they live on their own keys.
+// (`copy`, `move`, `mkdir`, `new`, `chmod`, `hardlink`, `symlink`, `delete`,
+// `run` — the `core/operations` registry). They are grouped by purpose
+// (Command, File, Info, Create, Edit, Delete), using each operation's own
+// `group` metadata, and alphabetized within each group (see
+// `filterPanelEntries`). The workspace-view toggle and Quit are listed
+// alongside the CLI operations; other TinyCmd actions keep their keys.
 //
 // For the selected operation, the panel binds its arguments from the live
 // context — a selection argument shows the SRC/DST pane's marked paths (falling
 // back to the cursor entry) and lets the user toggle individual items; a
 // destination argument resolves to the DST pane's directory; textual arguments
-// (a name, a buffer label, a shell command) are typed in place.
+// (a name, a buffer label, a shell command) are typed in place. `chmod` binds
+// its MODE to the permission grid from `core/permissions`.
 //
 // The selection the user tweaks is *transient*: it lives in the draft bindings
 // (`session.panelDraft`), never in the real pane marks. When the draft runs,
 // each selection argument is encoded as a self-contained `$paths:[…]` token, so
-// the resolved paths survive an async confirm (see `expandArg`). The same draft
-// assembles the command line the panel previews (`panelCommand`), so the user
-// sees how the current selection maps to the operation before running it.
+// the resolved paths survive an async confirm (see `expandArg`). The draft can
+// also be rendered as a shell-quoted command (`panelCommand`), while the panel
+// itself presents the arguments and an explicit Run action.
 // Everything here is pure: the caller owns the cells; the panel commands in
-// `core/commands` assemble and run.
+// `core/commands` assemble and run. Picker path resolution and row shaping live
+// in `core/picker`.
 
-import { hasMatch, score } from "../vendor/fzy.js"
+import { hasMatch } from "../vendor/fzy.js"
 import { currentPaneId, PANE_BUFFERS, PANE_LABELS } from "./pane.js"
 import { basename, parent } from "./path.js"
-import { getOperations, pathToken } from "./operations.js"
+import { getOperations, pathToken, shellQuote } from "./operations.js"
+import { PERMISSION_BITS, PERMISSION_CLASSES, permissionItems, permissionOctal, permissionText } from "./permissions.js"
 
 // Constant: PANEL_FOCUS
 // The two regions the panel's focus ring moves through: "ops" (the filter and
@@ -36,89 +41,132 @@ import { getOperations, pathToken } from "./operations.js"
 // right pane, where a textual argument owns the keyboard and Space toggles a
 // selection item).
 const PANEL_FOCUS = { OPS: "ops", ARGS: "args" }
+const PANEL_GROUPS = ["Command", "File", "Info", "Create", "Edit", "Delete"]
 
 // Function: panelEntries
-// The entries the panel lists: the CLI operations. They are the only namespace
-// — the internal TinyCmd actions are reached by their own keys, not the panel.
+// The entries the panel lists: the categorized CLI operations (each carries its
+// own `group`), the workspace-view toggle (named `view` like File's preview
+// operation, but in the Command group) and Quit.
 function panelEntries() {
-	return getOperations()
-		.filter((op) => !op.hidden)
+	const entries = getOperations()
+		.filter((op) => !op.hidden && op.group)
 		.map((op) => ({
 			id: `op:${op.name}`,
 			name: op.name,
-			summary: `${op.signature ?? ""}`.replace(/^\S+\s*/, ""),
-			signature: op.signature ?? "",
+			group: op.group,
 			risk: op.risk ?? null,
 			matchNames: [op.name, ...(op.aliases ?? [])],
 			op,
 		}))
+	entries.push({
+		id: "command:view",
+		name: "view",
+		group: "Command",
+		risk: null,
+		matchNames: ["view"],
+		commandId: "view.toggleMode",
+		// A no-argument command still shows where it acts.
+		showPath: true,
+	})
+	entries.push({
+		id: "command:reload",
+		name: "reload",
+		group: "Command",
+		risk: null,
+		matchNames: ["reload", "refresh"],
+		commandId: "pane.reload",
+		// A no-argument command still shows where it acts.
+		showPath: true,
+	})
+	entries.push({
+		id: "command:quit",
+		name: "quit",
+		group: "Command",
+		risk: null,
+		matchNames: ["quit", "q"],
+		commandId: "app.quit",
+	})
+	return entries
 }
 
 // Function: compareEntries
-// The panel's default ordering: alphabetically by name.
+// The panel's fixed category order, then alphabetical command order.
 function compareEntries(a, b) {
-	return `${a?.name ?? ""}`.localeCompare(`${b?.name ?? ""}`)
-}
-
-// Function: entryScore
-// The match importance of an entry for a query: the best fzy score across its
-// names, or `-Infinity` when none matches (only the signature does).
-function entryScore(entry, query) {
-	let best = -Infinity
-	for (const name of entry.matchNames ?? []) {
-		const haystack = `${name}`.toLowerCase()
-		if (hasMatch(query, haystack)) best = Math.max(best, score(query, haystack))
-	}
-	return best
+	const groupA = PANEL_GROUPS.indexOf(`${a?.group ?? "File"}`)
+	const groupB = PANEL_GROUPS.indexOf(`${b?.group ?? "File"}`)
+	const rankA = groupA < 0 ? PANEL_GROUPS.length : groupA
+	const rankB = groupB < 0 ? PANEL_GROUPS.length : groupB
+	return rankA - rankB || `${a?.name ?? ""}`.localeCompare(`${b?.name ?? ""}`)
 }
 
 // Function: filterPanelEntries
-// Narrows the entry list by a typed query and orders it: no query lists the
-// operations alphabetically; a query ranks the matches by importance (the fzy
-// score of the best name match, so `open` outranks `copy` for `op`), ties
-// alphabetical. A query that only matches an operation's signature (`buf` ->
-// `sel [+|-][BUF] PATH...`) keeps it listable, at the bottom.
+// Narrows the entry list by command name or alias and keeps the fixed category
+// order and alphabetical order within each group.
 function filterPanelEntries(entries, query) {
 	const list = entries ?? []
 	const q = `${query ?? ""}`.trim().toLowerCase()
 	if (!q) return [...list].sort(compareEntries)
-	const ranked = []
-	for (const entry of list) {
-		const rank = entryScore(entry, q)
-		const signatureMatch = `${entry.signature ?? ""}`.toLowerCase().includes(q)
-		if (rank === -Infinity && !signatureMatch) continue
-		ranked.push({ entry, score: rank })
-	}
-	ranked.sort((a, b) => (a.score !== b.score ? b.score - a.score : compareEntries(a.entry, b.entry)))
-	return ranked.map((match) => match.entry)
+	return list
+		.filter((entry) => (entry.matchNames ?? []).some((name) => hasMatch(q, `${name}`.toLowerCase())))
+		.sort(compareEntries)
 }
 
 // Function: panelEntryRows
-// Projects the filtered entries into the flat list the command-list column
-// renders: one `op` row per entry, tagged with its index in the *entries* list
+// Projects filtered entries into the command-list column: a group heading and
+// one name-only `op` row per entry, tagged with its index in the *entries* list
 // (what the cursor `panelOpIndex` addresses).
 function panelEntryRows(entries) {
-	return (entries ?? []).map((entry, index) => ({
-		type: "op",
-		id: entry.id,
-		entryIndex: index,
-		name: entry.name,
-		summary: entry.summary,
-		risk: entry.risk,
-	}))
+	const rows = []
+	let previousGroup = null
+	for (let index = 0; index < (entries ?? []).length; index++) {
+		const entry = entries[index]
+		const group = entry.group ?? "File"
+		if (group !== previousGroup) {
+			rows.push({ type: "group", key: `group:${group.toLowerCase()}`, name: group, group })
+			previousGroup = group
+		}
+		rows.push({
+			type: "op",
+			key: entry.id,
+			entryIndex: index,
+			name: entry.name,
+			group,
+			risk: entry.risk,
+		})
+	}
+	return rows
+}
+
+// Function: explorerColumnId
+// The column an explorer argument draws from: the *focused* one, so focusing
+// the parent mirror selects from its own listing — the current directory, a
+// directory — and focusing the preview selects from the directory it mirrors.
+// A focused column without a listing (the inspector over a file) falls back to
+// the pane that owns the current directory, matching `core/commands#pane`.
+function explorerColumnId(session) {
+	const active = session.active?.value
+	if (active === "parent") return active
+	if (
+		active === "preview" &&
+		session.showPreview?.value &&
+		session.previewEntry?.value?.isDir &&
+		!session.preview?.value
+	) {
+		return active
+	}
+	return currentPaneId(session)
 }
 
 // Function: resolvePaneId
 // Maps an argument role to a pane id: "source" -> the working pane (SRC in
-// commander; the pane the explorer is actually browsing, which may be either
-// side), "dest" -> DST (right), anything else -> the pane holding the current
-// directory (never an auxiliary column: operations run against the directory
-// being browsed).
+// commander; in explorer the focused column, which may be either side of the
+// chain), "dest" -> DST (right), anything else -> the pane holding the current
+// directory (the focused column in explorer, never an auxiliary column with no
+// listing, so operations run against what the cursor shows).
 function resolvePaneId(session, role) {
 	if (role === "dest") return "right"
-	if (role === "source") {
-		return session.viewMode?.value === "explorer" ? currentPaneId(session) : "left"
-	}
+	if (session.viewMode?.value === "explorer") return explorerColumnId(session)
+	if (role === "source") return "left"
 	return currentPaneId(session)
 }
 
@@ -163,6 +211,9 @@ function bindArg(session, arg, index) {
 	const role = arg.role ?? "active"
 	const common = {
 		index,
+		// Display order in the argument pane; the argv order stays the
+		// operation's own (see `panelRowList` and `argTokens`).
+		panelOrder: arg.panelOrder ?? index,
 		name: arg.name,
 		kind: arg.kind,
 		role,
@@ -185,6 +236,21 @@ function bindArg(session, arg, index) {
 			value: "",
 		}
 	}
+	if (arg.kind === "permissions") {
+		// Seed the checkboxes from the first selected path's current mode, so
+		// opening chmod starts on the file's real permissions rather than a
+		// generic 644. A path outside the listing falls back by kind.
+		const pane = session.panes[resolvePaneId(session, role)]
+		const entries = entryIndex(pane)
+		const path = paneSelectionPaths(pane)[0]
+		const entry = path ? entries.get(path) : null
+		const mode = Number.isInteger(entry?.mode)
+			? entry.mode & 0o777
+			: entry?.isDir
+				? 0o755
+				: 0o644
+		return { ...common, multi: true, items: permissionItems(mode) }
+	}
 	if (arg.kind === "dest" || arg.kind === "path") {
 		// A destination or a path argument is typeable in place, like a
 		// literal, and additionally browsable through the panel's file picker
@@ -194,7 +260,12 @@ function bindArg(session, arg, index) {
 		// empty for the picker (or the user) to fill.
 		const mode = arg.kind === "dest" ? "dir" : arg.mode ?? "any"
 		const commander = (session.viewMode?.value ?? "commander") !== "explorer"
-		const value = mode === "dir" && commander ? session.panes?.right?.path?.value ?? "" : ""
+		const value =
+			arg.prefill === "current"
+				? (session.activePath?.value ?? "")
+				: mode === "dir" && commander
+					? (session.panes?.right?.path?.value ?? "")
+					: ""
 		return { ...common, textual: true, picker: true, mode, items: [], value }
 	}
 	if (arg.kind === "buffer") {
@@ -228,6 +299,7 @@ function argTokens(bindings) {
 			const paths = selectedPaths(binding)
 			return paths.length ? pathToken(paths) : ""
 		}
+		if (binding.kind === "permissions") return permissionOctal(binding)
 		if (binding.kind === "dest") return binding.value ?? ""
 		return `${binding.value ?? ""}`.trim()
 	})
@@ -269,17 +341,6 @@ function missingArg(bindings) {
 	return missingBinding(bindings)?.name ?? null
 }
 
-// Function: shellQuote
-// Quotes a token for display as it would appear in a shell: bare when it is
-// already safe (`/home/a`), single-quoted when it contains spaces or shell
-// metacharacters (`'my notes.txt'`). Only the last path segment matters in
-// practice, but quoting the whole token keeps the preview copy-pasteable.
-function shellQuote(token) {
-	const text = `${token ?? ""}`
-	if (text === "") return "''"
-	return /^[A-Za-z0-9_@%+=:,.\/-]+$/.test(text) ? text : `'${text.replace(/'/g, `'\\''`)}'`
-}
-
 // Function: panelCommand
 // The command line the draft maps to: each argument rendered as the value it
 // contributes — a selection as its selected paths, a destination/textual arg
@@ -296,6 +357,10 @@ function panelCommand(bindings) {
 			else if (binding.optional !== true) parts.push(`«${binding.name}»`)
 			continue
 		}
+		if (binding.kind === "permissions") {
+			parts.push(permissionOctal(binding))
+			continue
+		}
 		const value = `${binding.value ?? ""}`.trim()
 		if (value) parts.push(shellQuote(value))
 		else if (binding.optional !== true) parts.push(`«${binding.name}»`)
@@ -321,6 +386,7 @@ function panelSummary(binding) {
 		const count = selectedPaths(binding).length
 		return `${pane} · ${count} selected`
 	}
+	if (binding.kind === "permissions") return permissionText(binding)
 	if (binding.kind === "dest" || binding.kind === "path") return binding.value || "(none)"
 	if (binding.kind === "buffer") return binding.value || "(active)"
 	return binding.value ? binding.value : "(empty)"
@@ -336,7 +402,12 @@ function panelSummary(binding) {
 // list rows are; this stays pure and index-stable.
 function panelRowList(bindings) {
 	const rows = []
-	for (const binding of bindings ?? []) {
+	// The pane may show arguments in a different order from the argv (PATH
+	// before MODE/OWNER); the binding `index` still keys the draft.
+	const ordered = [...(bindings ?? [])].sort(
+		(a, b) => (a.panelOrder ?? a.index) - (b.panelOrder ?? b.index),
+	)
+	for (const binding of ordered) {
 		const multi = binding.multi === true
 		const items = binding.items ?? []
 		// A selection that resolves to a single path is not a list: it renders
@@ -355,6 +426,7 @@ function panelRowList(bindings) {
 			optional: binding.optional,
 			variadic: binding.variadic,
 			textual: binding.textual,
+			editable: binding.textual === true,
 			picker: binding.picker === true,
 			mode: binding.mode ?? null,
 			multi,
@@ -363,6 +435,37 @@ function panelRowList(bindings) {
 			count: items.length,
 		})
 		if (single) continue
+		// A permission argument renders as one row per class (u/g/o) with its
+		// three bits as clickable cells, rather than nine checkbox rows. The
+		// bit cursor (`panelPermBit`) selects the cell Space toggles.
+		if (binding.kind === "permissions") {
+			for (let c = 0; c < PERMISSION_CLASSES.length; c++) {
+				const permissionClass = PERMISSION_CLASSES[c]
+				const rowIndex = rows.length
+				const bits = PERMISSION_BITS.map((bit, i) => {
+					const itemIndex = c * PERMISSION_BITS.length + i
+					return {
+						id: bit.id,
+						selected: items[itemIndex]?.selected === true,
+						itemIndex,
+					}
+				})
+				rows.push({
+					type: "perm",
+					key: `perm:${binding.index}:${permissionClass.id}`,
+					rowIndex,
+					argIndex: binding.index,
+					classId: permissionClass.id,
+					label: permissionClass.label,
+					bits,
+					// Click payloads: arg index, item index, row index.
+					keyR: `${binding.index}:${bits[0].itemIndex}:${rowIndex}`,
+					keyW: `${binding.index}:${bits[1].itemIndex}:${rowIndex}`,
+					keyX: `${binding.index}:${bits[2].itemIndex}:${rowIndex}`,
+				})
+			}
+			continue
+		}
 		for (let i = 0; i < items.length; i++) {
 			const item = items[i]
 			const selected = item.selected
@@ -392,23 +495,6 @@ function rowAt(rows, index) {
 	return (rows ?? [])[index] ?? null
 }
 
-// Function: pickerRowList
-// Flattens the picker's visible listing into the rows the panel's argument
-// column renders while a path is being picked. The shape mirrors a
-// file-listing row (`name`, `path`, `isDir`) so the shared row component can
-// render both; a symlink carries its raw target for the summary.
-function pickerRowList(entries) {
-	return (entries ?? []).map((entry) => ({
-		type: "entry",
-		key: entry.path,
-		name: entry.name,
-		path: entry.path,
-		isDir: entry.isDir === true,
-		isSymlink: entry.isSymlink === true,
-		target: entry.target ?? null,
-	}))
-}
-
 // Function: isTextualRow
 // True when the cursor row is an argument header that takes free text, so the
 // panel focuses its edit field.
@@ -450,6 +536,7 @@ export { decodePathToken, pathToken } from "./operations.js"
 
 export {
 	PANEL_FOCUS,
+	PANEL_GROUPS,
 	argvFor,
 	bindArg,
 	bindArgs,
@@ -465,7 +552,6 @@ export {
 	panelRunnable,
 	panelSummary,
 	paneSelectionPaths,
-	pickerRowList,
 	rowAt,
 	selectedPaths,
 	withArgValue,

package/src/js/tcmd/core/path.js

@@ -37,9 +37,11 @@ function split(p) {
 
 // Function: extname
 // Lowercased extension of the last segment, without the dot; null when the
-// name has no extension (or is a dotfile).
+// name has no extension (or is a dotfile). A bare filename (no separator), the
+// common case when building a listing, skips the `basename` split.
 function extname(p) {
-	const name = basename(p)
+	const text = `${p ?? ""}`
+	const name = text.indexOf(SEP) < 0 ? text : basename(text)
 	const at = name.lastIndexOf(".")
 	return at > 0 ? name.slice(at + 1).toLowerCase() : null
 }
@@ -52,6 +54,31 @@ function prefix(p, count) {
 	return SEP + parts.slice(0, Math.max(0, count)).join(SEP)
 }
 
-export { SEP, basename, extname, join, normalize, parent, prefix, split }
+// Function: relative
+// Expresses `target` relative to the absolute directory `base`, using `..`
+// segments when it sits outside: `relative("/a", "/a/b/c")` is `"b/c"` and
+// `relative("/a/b", "/a/c")` is `"../c"`. Equal paths collapse to `"."`. A
+// non-absolute input comes back unchanged, since there is nothing meaningful
+// to relativize against.
+function relative(base, target) {
+	const from = `${base ?? ""}`
+	const to = `${target ?? ""}`
+	if (!from.startsWith(SEP) || !to.startsWith(SEP)) return to
+	const baseParts = split(from)
+	const targetParts = split(to)
+	let common = 0
+	while (
+		common < baseParts.length &&
+		common < targetParts.length &&
+		baseParts[common] === targetParts[common]
+	) {
+		common += 1
+	}
+	const up = Array.from({ length: baseParts.length - common }, () => "..")
+	const down = targetParts.slice(common)
+	return [...up, ...down].join(SEP) || "."
+}
+
+export { SEP, basename, extname, join, normalize, parent, prefix, relative, split }
 
 // EOF

package/src/js/tcmd/core/permissions.js

@@ -0,0 +1,107 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-10-22
+
+// Module: tcmd/core/permissions
+// POSIX permission bits as the command panel edits them: the nine `u/g/o` ×
+// `r/w/x` toggles `chmod` binds its MODE argument to. The tables are the single
+// source of truth for the display order, the octal values and the `rwx`
+// rendering; the panel projects them into rows and the argument row component
+// renders the three cells of each class.
+//
+// Everything here is pure: the binding is the caller's, and the numeric/octal
+// conversions do not mutate it.
+
+// Constant: PERMISSION_CLASSES
+// The permission classes in display order (owner, group, other).
+const PERMISSION_CLASSES = [
+	{ id: "u", label: "user" },
+	{ id: "g", label: "group" },
+	{ id: "o", label: "other" },
+]
+
+// Constant: PERMISSION_BITS
+// The bits of each class in display order (read, write, execute).
+const PERMISSION_BITS = [
+	{ id: "r", label: "read" },
+	{ id: "w", label: "write" },
+	{ id: "x", label: "execute" },
+]
+
+// Constant: PERMISSION_VALUES
+// The octal value of each `class:bit` key.
+const PERMISSION_VALUES = {
+	"u:r": 0o400, "u:w": 0o200, "u:x": 0o100,
+	"g:r": 0o040, "g:w": 0o020, "g:x": 0o010,
+	"o:r": 0o004, "o:w": 0o002, "o:x": 0o001,
+}
+
+// Function: permissionItems
+// The nine `u/g/o` × `r/w/x` toggles for a permission argument, seeded from an
+// existing file mode. Each item is a checkbox in the panel's item list: its
+// `key` is the stable `class:bit` key the token builder reads back.
+function permissionItems(mode) {
+	const bits = Number(mode) & 0o777
+	const items = []
+	for (const permissionClass of PERMISSION_CLASSES) {
+		for (const bit of PERMISSION_BITS) {
+			const key = `${permissionClass.id}:${bit.id}`
+			items.push({
+				key,
+				name: bit.label,
+				parent: permissionClass.label,
+				isDir: false,
+				selected: (bits & PERMISSION_VALUES[key]) !== 0,
+			})
+		}
+	}
+	return items
+}
+
+// Function: permissionMode
+// The numeric mode a permission binding currently selects.
+function permissionMode(binding) {
+	let mode = 0
+	for (const item of binding?.items ?? []) {
+		if (item.selected) mode |= PERMISSION_VALUES[item.key] ?? 0
+	}
+	return mode
+}
+
+// Function: permissionOctal
+// The three-digit octal token a permission binding contributes to argv.
+function permissionOctal(binding) {
+	return permissionMode(binding).toString(8).padStart(3, "0")
+}
+
+// Function: permissionSymbolic
+// The `rwx`-style rendering of a numeric mode.
+function permissionSymbolic(mode) {
+	return PERMISSION_CLASSES.map((permissionClass) =>
+		PERMISSION_BITS.map((bit) =>
+			mode & PERMISSION_VALUES[`${permissionClass.id}:${bit.id}`] ? bit.id : "-",
+		).join(""),
+	).join("")
+}
+
+// Function: permissionText
+// The binding's value as the panel shows it: the octal mode and its symbolic
+// form (`644 · rw-r--r--`).
+function permissionText(binding) {
+	const mode = permissionMode(binding)
+	return `${permissionOctal(binding)} · ${permissionSymbolic(mode)}`
+}
+
+export {
+	PERMISSION_BITS,
+	PERMISSION_CLASSES,
+	PERMISSION_VALUES,
+	permissionItems,
+	permissionMode,
+	permissionOctal,
+	permissionSymbolic,
+	permissionText,
+}
+
+// EOF