@carlesandres/house 0.4.13 → 0.5.0

package/src/io/clipboard.ts

@@ -1,53 +0,0 @@
-/**
- * Best-effort clipboard write for macOS/Linux.
- *
- * The selected tool is fed through stdin so large or multiline markdown can be
- * copied without shell quoting issues.
- */
-
-export interface ClipboardCommand {
-	readonly cmd: string
-	readonly args: readonly string[]
-}
-
-type WhichFn = (command: string) => string | null | undefined
-
-interface CopyToClipboardDeps {
-	readonly platform?: NodeJS.Platform
-	readonly which?: WhichFn
-	readonly spawn?: (command: ClipboardCommand, text: string) => Promise<number>
-}
-
-export const resolveClipboardCommand = (
-	platform: NodeJS.Platform,
-	which: WhichFn,
-): ClipboardCommand | null => {
-	if (platform === "darwin") return { cmd: "pbcopy", args: [] }
-	if (platform !== "linux") return null
-	if (which("wl-copy")) return { cmd: "wl-copy", args: [] }
-	if (which("xclip")) return { cmd: "xclip", args: ["-selection", "clipboard"] }
-	return null
-}
-
-const spawnClipboardCommand = async (command: ClipboardCommand, text: string): Promise<number> => {
-	const proc = Bun.spawn([command.cmd, ...command.args], {
-		stdin: new Response(text),
-		stdout: "ignore",
-		stderr: "ignore",
-	})
-	return await proc.exited
-}
-
-export const copyTextToClipboard = async (
-	text: string,
-	{
-		platform = process.platform,
-		which = Bun.which.bind(Bun),
-		spawn = spawnClipboardCommand,
-	}: CopyToClipboardDeps = {},
-): Promise<void> => {
-	const command = resolveClipboardCommand(platform, which)
-	if (!command) throw new Error("no clipboard tool found")
-	const exitCode = await spawn(command, text)
-	if (exitCode !== 0) throw new Error("clipboard command failed")
-}

package/src/io/editor.ts

@@ -1,162 +0,0 @@
-/**
- * Resolve `$VISUAL` / `$EDITOR` into a spawnable `{ cmd, args }`.
- *
- * The string is POSIX shell-split so users with values like
- * `code --wait` or `"/Applications/Sublime Text/subl" --wait` get the
- * expected argv. We deliberately do *not* shell out via `sh -c`: the
- * caller appends the file path as a separate argv element, which avoids
- * command-injection risk for paths containing shell metacharacters.
- *
- * Resolution order: `$VISUAL` → `$EDITOR` → `null`. No silent fallback to
- * `vi`; the caller surfaces a footer notice when neither is set.
- */
-
-export interface ResolvedEditor {
-	readonly cmd: string
-	readonly args: readonly string[]
-}
-
-/**
- * Split a command string the way `sh` would for the simple cases users
- * actually put in `$EDITOR`: single quotes (literal), double quotes
- * (with `\"`, `\\` escapes), backslash escapes outside quotes, and
- * whitespace separation. No variable expansion, no globbing, no command
- * substitution — by design. If the input is unbalanced (an unclosed
- * quote), the partial token is emitted as-is so the caller's spawn
- * surfaces a real error instead of us throwing.
- */
-export const splitEditorString = (input: string): string[] => {
-	const tokens: string[] = []
-	let buf = ""
-	let inSingle = false
-	let inDouble = false
-	let pendingToken = false
-
-	for (let i = 0; i < input.length; i++) {
-		const ch = input[i]!
-		if (inSingle) {
-			if (ch === "'") inSingle = false
-			else buf += ch
-			continue
-		}
-		if (inDouble) {
-			if (ch === "\\" && i + 1 < input.length) {
-				const next = input[i + 1]!
-				// In double quotes, `sh` only treats `\` as an escape before
-				// `$`, `` ` ``, `"`, `\`, or newline. Otherwise the backslash
-				// is literal. We collapse it for `"` and `\` (the cases users
-				// hit with Windows-style paths in double quotes) and keep it
-				// literal otherwise.
-				if (next === '"' || next === "\\") {
-					buf += next
-					i++
-					continue
-				}
-			}
-			if (ch === '"') {
-				inDouble = false
-				continue
-			}
-			buf += ch
-			continue
-		}
-		if (ch === "'") {
-			inSingle = true
-			pendingToken = true
-			continue
-		}
-		if (ch === '"') {
-			inDouble = true
-			pendingToken = true
-			continue
-		}
-		if (ch === "\\" && i + 1 < input.length) {
-			buf += input[i + 1]!
-			i++
-			pendingToken = true
-			continue
-		}
-		if (ch === " " || ch === "\t") {
-			if (pendingToken) {
-				tokens.push(buf)
-				buf = ""
-				pendingToken = false
-			}
-			continue
-		}
-		buf += ch
-		pendingToken = true
-	}
-	if (pendingToken) tokens.push(buf)
-	return tokens
-}
-
-/**
- * Pick the user's editor from env vars. Returns `null` when neither
- * `$VISUAL` nor `$EDITOR` is set to a non-empty, non-whitespace value.
- *
- * `env` is parameterised so tests don't need to mutate `process.env`.
- */
-export const resolveEditor = (
-	env: Readonly<Record<string, string | undefined>>,
-): ResolvedEditor | null => {
-	const raw = pickEnv(env["VISUAL"]) ?? pickEnv(env["EDITOR"])
-	if (raw == null) return null
-	const parts = splitEditorString(raw)
-	if (parts.length === 0) return null
-	const [cmd, ...args] = parts
-	if (!cmd) return null
-	return { cmd, args }
-}
-
-const pickEnv = (value: string | undefined): string | null => {
-	if (value == null) return null
-	const trimmed = value.trim()
-	return trimmed.length === 0 ? null : trimmed
-}
-
-/** Result of a launched editor session. Never throws — every failure is
- *  surfaced as a tagged value so the caller can decide UX. */
-export type EditorRunResult =
-	| { readonly ok: true; readonly exitCode: number }
-	| {
-			readonly ok: false
-			readonly reason: "spawn-failed" | "non-zero"
-			readonly detail?: string
-	  }
-
-export interface OpenInEditorOptions {
-	readonly editor: ResolvedEditor
-	readonly filePath: string
-}
-
-/**
- * Launch the resolved editor on `filePath`, inheriting stdio so the
- * editor takes over the TTY. Caller is responsible for suspending /
- * resuming the renderer around this call (see Browser.tsx).
- *
- * The file path is passed as a separate argv element — never interpolated
- * into a shell string — so paths with shell metacharacters can't be
- * misinterpreted.
- *
- * Windows is unsupported (see #129). The PATHEXT gap that breaks `.cmd`
- * shims (`code.cmd`, `nvim.cmd`) is tracked specifically in #128.
- */
-export const openInEditor = async ({
-	editor,
-	filePath,
-}: OpenInEditorOptions): Promise<EditorRunResult> => {
-	const argv = [editor.cmd, ...editor.args, filePath]
-	try {
-		const proc = Bun.spawn(argv, {
-			stdin: "inherit",
-			stdout: "inherit",
-			stderr: "inherit",
-		})
-		const exitCode = await proc.exited
-		if (exitCode === 0) return { ok: true, exitCode }
-		return { ok: false, reason: "non-zero", detail: String(exitCode) }
-	} catch (err) {
-		return { ok: false, reason: "spawn-failed", detail: String(err) }
-	}
-}

package/src/io/readFile.ts

@@ -1,14 +0,0 @@
-import { readFile } from "node:fs/promises"
-import { Data, Effect } from "effect"
-
-export class FileReadError extends Data.TaggedError("FileReadError")<{
-	readonly path: string
-	readonly cause: unknown
-}> {}
-
-/** Read a UTF-8 text file. Errors as `FileReadError`. */
-export const readFileText = (path: string): Effect.Effect<string, FileReadError> =>
-	Effect.tryPromise({
-		try: () => readFile(path, "utf8"),
-		catch: (cause) => new FileReadError({ path, cause }),
-	})

package/src/keymap/browser.ts

@@ -1,335 +0,0 @@
-/**
- * Browser keymap — the data backing `Browser.tsx`'s `useKeyboard` handler.
- */
-
-import type { FileEntry } from "../discovery/walk.ts"
-import type { KeyBinding } from "./keymap.ts"
-
-export type BrowserFocus = "sidebar" | "reader"
-
-export interface BrowserCtx {
-	readonly files: readonly FileEntry[]
-	/** True iff `files[selectedIndex]` resolves to an entry. The honest
-	 *  predicate for File-group actions (`O`, `E`, `[`, `]`): with debounced
-	 *  filter and sticky auto-select, `files.length > 0` can be true while
-	 *  `selectedIndex` is invalid for the displayed list. See #115. */
-	readonly hasSelected: boolean
-	readonly focus: BrowserFocus
-	/** User's sticky sidebar preference. Visibility is `shown || focus==="sidebar"`. */
-	readonly sidebarShown: boolean
-	readonly filterOpen: boolean
-	readonly restoreFilterOnSidebarFocus: boolean
-	/** Current applied/edited filter query. Used by `filter.clearOrOpen`'s
-	 *  hint gate so the hint only appears when there is something to clear. */
-	readonly filterQuery: string
-	readonly paletteOpen: boolean
-	readonly wrapEnabled: boolean
-	readonly setFocus: (next: BrowserFocus | ((prev: BrowserFocus) => BrowserFocus)) => void
-	readonly setSelectedIndex: (updater: (prev: number) => number) => void
-	/** Toggle `shown` and adjust focus per DESIGN.md §7.1 (see s-behavior table). */
-	readonly toggleShown: () => void
-	readonly openFilter: () => void
-	/** Clear the current filter query and open the filter modal in a single
-	 *  action. Bound to `\` so users can reset a stranded zero-match filter
-	 *  without first reopening with `/` and backspacing. */
-	readonly clearAndOpenFilter: () => void
-	readonly openPalette: () => void
-	readonly toggleWrap: () => void
-	readonly cycleTheme: (delta: 1 | -1) => void
-	readonly toggleTone: () => void
-	readonly quit: () => void
-	/** Start (or retarget) the HTML preview server on the focused file. */
-	readonly serveCurrent: () => void
-	/** Suspend the TUI, hand the TTY to `$EDITOR`, resume and re-read on
-	 *  exit. No-op when nothing is selected; gating is the binding's job. */
-	readonly editCurrent: () => void
-	/** Copy the currently-selected file's raw contents to the system
-	 *  clipboard. No-op when nothing is selected; palette gating is the
-	 *  primary availability control. */
-	readonly copyCurrentContents: () => void
-	/** Toggle hidden + gitignored discovery axes together (#145 — UI sugar
-	 *  for `shift+a`; the underlying flags stay independent everywhere
-	 *  else). Snapshots the current selected path so it can be restored
-	 *  once the re-walk completes. */
-	readonly toggleAll: () => void
-}
-
-/** Step size for shift+j/k and the space/b/page keys. Constant for v1; could
- *  later be derived from the visible window height. */
-const JUMP = 8
-
-const clamp = (n: number, min: number, max: number) => Math.max(min, Math.min(max, n))
-const lastIndex = (c: BrowserCtx) => Math.max(0, c.files.length - 1)
-const haveFiles = (c: BrowserCtx) => c.files.length > 0
-const hasSelected = (c: BrowserCtx) => c.hasSelected
-const stepBy = (c: BrowserCtx, delta: number) =>
-	c.setSelectedIndex((i) => clamp(i + delta, 0, lastIndex(c)))
-
-const inSidebar = (c: BrowserCtx) => c.focus === "sidebar"
-const filterClosed = (c: BrowserCtx) => !c.filterOpen
-const paletteClosed = (c: BrowserCtx) => !c.paletteOpen
-const inputClosed = (c: BrowserCtx) => filterClosed(c) && paletteClosed(c)
-const inReader = (c: BrowserCtx) => c.focus === "reader"
-const inSidebarWithFiles = (c: BrowserCtx) => inSidebar(c) && haveFiles(c)
-/** Reader-only sibling-step gate: needs a current selection plus a sibling
- *  to step to. `hasSelected` implies `files.length >= 1`, so `>= 2` is the
- *  meaningful extra condition. */
-const inReaderWithSibling = (c: BrowserCtx) => inReader(c) && hasSelected(c) && c.files.length >= 2
-
-export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
-	// Global
-	{
-		id: "quit",
-		group: "Global",
-		description: "Quit",
-		hint: "quit",
-		keys: ["q", "ctrl+c"],
-		hintWhen: inputClosed,
-		run: (c) => c.quit(),
-	},
-	{
-		id: "focus.toggle",
-		group: "Global",
-		description: "Toggle focus (sidebar ↔ reader)",
-		hint: "focus",
-		keys: ["tab"],
-		run: (c) => {
-			if (c.focus === "reader" && c.restoreFilterOnSidebarFocus) {
-				c.openFilter()
-			} else {
-				c.setFocus((f) => (f === "sidebar" ? "reader" : "sidebar"))
-			}
-		},
-	},
-	{
-		id: "sidebar.toggle",
-		group: "Global",
-		description: "Toggle sidebar visibility",
-		hint: "sidebar",
-		keys: ["s"],
-		hintWhen: inputClosed,
-		run: (c) => c.toggleShown(),
-	},
-	{
-		id: "filter.open",
-		group: "Sidebar",
-		description: "Filter files (fuzzy match on path)",
-		hint: "filter",
-		keys: ["/"],
-		// Fires from anywhere except inside an already-open filter. `openFilter`
-		// itself force-opens the sidebar and moves focus there, so the binding
-		// no longer needs to gate on focus or sidebar visibility.
-		when: filterClosed,
-		run: (c) => c.openFilter(),
-	},
-	{
-		id: "filter.clearOrOpen",
-		group: "Sidebar",
-		description: "Clear filter",
-		hint: "clear",
-		keys: ["ctrl+\\"],
-		// Fires from anywhere outside the filter modal via the keymap.
-		// Inside the filter modal it's intercepted directly in Browser.tsx
-		// (the filter mode owns key handling), but the action is the same —
-		// clear input, keep modal open. Palette branches short-circuit
-		// dispatch in Browser.tsx, so we don't need to gate on them for
-		// behavior; the `hintWhen` gate keeps the footer hint from showing
-		// when there's nothing to clear or when a modal owns the input.
-		// Chord chosen over single `\` so the binding works inside the
-		// filter input without colliding with the typed character; ctrl+u
-		// is deliberately left to its reader/sidebar half-page-up role to
-		// avoid overload.
-		when: filterClosed,
-		hintWhen: (c) => filterClosed(c) && !c.paletteOpen && c.filterQuery.length > 0,
-		run: (c) => c.clearAndOpenFilter(),
-	},
-	{
-		id: "palette.open",
-		group: "Global",
-		description: "Command palette",
-		hint: "palette",
-		keys: ["ctrl+p"],
-		// The filter modal handles this chord directly so the palette can open
-		// while filter input owns the rest of the keyboard. This gate keeps the
-		// normal dispatcher from reopening an already-open palette.
-		when: paletteClosed,
-		run: (c) => c.openPalette(),
-	},
-	{
-		id: "discovery.toggleAll",
-		group: "Sidebar",
-		description: "Show / hide hidden and gitignored files",
-		// No footer hint: shift+a is help/palette only. The footer hint row is
-		// already at width capacity on narrow viewports, and the toggle isn't
-		// a per-row action you reach for constantly.
-		keys: ["shift+a"],
-		// Selection-preservation logic lives in Browser.tsx — see the
-		// `pendingSelectionPath` ref. The toggle itself is session-only and
-		// does not write back to the TOML config.
-		run: (c) => c.toggleAll(),
-	},
-	{
-		id: "reader.wrap.toggle",
-		group: "Global",
-		description: "Toggle reader wrap",
-		hint: "wrap",
-		keys: ["w"],
-		hintWhen: inputClosed,
-		run: (c) => c.toggleWrap(),
-	},
-	{
-		id: "theme.next",
-		group: "Global",
-		description: "Next theme",
-		hint: "theme",
-		keys: ["t"],
-		hintWhen: inputClosed,
-		run: (c) => c.cycleTheme(1),
-	},
-	{
-		id: "theme.prev",
-		group: "Global",
-		description: "Previous theme",
-		keys: ["shift+t"],
-		run: (c) => c.cycleTheme(-1),
-	},
-	{
-		id: "theme.toneToggle",
-		group: "Global",
-		description: "Toggle dark / light tone",
-		keys: ["shift+l"],
-		run: (c) => c.toggleTone(),
-	},
-
-	// Sidebar
-	{
-		id: "sidebar.down",
-		group: "Sidebar",
-		description: "Move selection down",
-		keys: ["j", "down"],
-		when: inSidebarWithFiles,
-		run: (c) => stepBy(c, 1),
-	},
-	{
-		id: "sidebar.up",
-		group: "Sidebar",
-		description: "Move selection up",
-		keys: ["k", "up"],
-		when: inSidebarWithFiles,
-		run: (c) => stepBy(c, -1),
-	},
-	{
-		id: "sidebar.jumpDown",
-		group: "Sidebar",
-		description: `Jump down ${JUMP}`,
-		keys: ["shift+j"],
-		when: inSidebarWithFiles,
-		run: (c) => stepBy(c, JUMP),
-	},
-	{
-		id: "sidebar.jumpUp",
-		group: "Sidebar",
-		description: `Jump up ${JUMP}`,
-		keys: ["shift+k"],
-		when: inSidebarWithFiles,
-		run: (c) => stepBy(c, -JUMP),
-	},
-	{
-		id: "sidebar.pageDown",
-		group: "Sidebar",
-		description: "Page down",
-		keys: ["space", "pagedown", "ctrl+d"],
-		when: inSidebarWithFiles,
-		run: (c) => stepBy(c, JUMP),
-	},
-	{
-		id: "sidebar.pageUp",
-		group: "Sidebar",
-		description: "Page up",
-		keys: ["b", "pageup", "ctrl+u"],
-		when: inSidebarWithFiles,
-		run: (c) => stepBy(c, -JUMP),
-	},
-	{
-		id: "sidebar.top",
-		group: "Sidebar",
-		description: "Jump to first file",
-		keys: ["g"],
-		when: inSidebarWithFiles,
-		run: (c) => c.setSelectedIndex(() => 0),
-	},
-	{
-		id: "sidebar.bottom",
-		group: "Sidebar",
-		description: "Jump to last file",
-		keys: ["shift+g"],
-		when: inSidebarWithFiles,
-		run: (c) => c.setSelectedIndex(() => lastIndex(c)),
-	},
-	{
-		id: "sidebar.open",
-		group: "Sidebar",
-		description: "Open file (focus reader)",
-		hint: "open",
-		keys: ["return", "right", "l"],
-		when: inSidebar,
-		hintWhen: (c) => inSidebar(c) && hasSelected(c),
-		run: (c) => c.setFocus("reader"),
-	},
-
-	// File — actions on the currently-selected file. Gated on `hasSelected`
-	// (per #115) so they're available exactly when the reader has something
-	// to act on, regardless of focus or filter state.
-	{
-		id: "serve.current",
-		group: "File",
-		description: "Open current file in browser as HTML",
-		hint: "html",
-		keys: ["shift+o"],
-		when: hasSelected,
-		hintWhen: (c) => inputClosed(c) && hasSelected(c),
-		run: (c) => c.serveCurrent(),
-	},
-	{
-		id: "file.edit",
-		group: "File",
-		description: "Open current file in $EDITOR",
-		hint: "edit",
-		keys: ["shift+e"],
-		when: hasSelected,
-		hintWhen: (c) => inputClosed(c) && hasSelected(c),
-		run: (c) => c.editCurrent(),
-	},
-	{
-		// `[`/`]` keep the `inReader` clause so they're only typed from the
-		// reader (sidebar uses j/k for stepping). The File-group predicate is
-		// additive: needs a selection *and* a sibling to step to.
-		id: "reader.prevFile",
-		group: "File",
-		description: "Prev file",
-		hint: "prev",
-		keys: ["["],
-		when: inReaderWithSibling,
-		run: (c) => stepBy(c, -1),
-	},
-	{
-		id: "reader.nextFile",
-		group: "File",
-		description: "Next file",
-		hint: "next",
-		keys: ["]"],
-		when: inReaderWithSibling,
-		run: (c) => stepBy(c, 1),
-	},
-
-	// Reader
-	{
-		id: "reader.back",
-		group: "Reader",
-		description: "Back to sidebar",
-		hint: "back",
-		keys: ["escape", "left", "h"],
-		when: inReader,
-		run: (c) => c.setFocus("sidebar"),
-	},
-]

package/src/keymap/displayKey.ts

@@ -1,17 +0,0 @@
-/** Terminal-friendly display form for a binding's first key chord. */
-export const displayKey = (raw: string): string => {
-	switch (raw) {
-		case "return":
-			return "↵"
-		case "escape":
-			return "esc"
-		case "space":
-			return "␣"
-		case "pageup":
-			return "pgup"
-		case "pagedown":
-			return "pgdn"
-		default:
-			return raw
-	}
-}

package/src/keymap/keymap.ts

@@ -1,95 +0,0 @@
-/**
- * Tiny declarative keymap.
- *
- * Bindings are values: `{ id, description, keys, when?, run }`. A pure
- * `dispatch` looks up the first matching, enabled binding for a key event
- * and runs it. The same array also drives footer hints and command-palette
- * derivation, so there is one source of truth.
- *
- * Deliberately *not* a port of ghui's `@ghui/keymap`: no chord sequences,
- * no count prefixes, no scope contramaps. See DESIGN.md §12 for the full
- * trigger that would warrant adopting that machinery.
- */
-
-/** The shape of a parsed key event we care about. `KeyEvent` from opentui satisfies this. */
-export interface KeyMatch {
-	readonly name: string
-	readonly shift?: boolean
-	readonly ctrl?: boolean
-	readonly meta?: boolean
-}
-
-export interface KeyBinding<C> {
-	/** Stable id; used for tests and (later) command-palette routing. */
-	readonly id: string
-	/** Human-readable summary used by docs and palette command titles. */
-	readonly description: string
-	/** Key chords that trigger this binding, e.g. ["j", "down"], ["shift+k"], ["ctrl+c"]. */
-	readonly keys: readonly string[]
-	/** Optional grouping label for derived UI/documentation surfaces. */
-	readonly group?: string
-	/** Optional compact label for the footer hint row, e.g. "help" for `?:help`.
-	 *  Bindings without a hint are excluded from the footer. Order in the bindings
-	 *  array drives overflow priority (later bindings get truncated first). */
-	readonly hint?: string
-	/** If present, the binding only fires when this returns true. */
-	readonly when?: (ctx: C) => boolean
-	/** If present, the footer hint is shown only when this returns true. When
-	 *  absent, hint visibility falls back to `when`. Use when a binding's
-	 *  dispatch gate is broader than the situations where the hint is useful
-	 *  (e.g. "clear filter" fires from anywhere but only deserves a hint when
-	 *  there is actually a filter to clear). */
-	readonly hintWhen?: (ctx: C) => boolean
-	readonly run: (ctx: C) => void
-}
-
-interface ParsedChord {
-	readonly key: string
-	readonly shift: boolean
-	readonly ctrl: boolean
-	readonly meta: boolean
-}
-
-const parseChord = (raw: string): ParsedChord => {
-	const parts = raw.toLowerCase().split("+")
-	const key = parts.at(-1) ?? ""
-	return {
-		key,
-		shift: parts.includes("shift"),
-		ctrl: parts.includes("ctrl"),
-		meta: parts.includes("meta"),
-	}
-}
-
-const chordMatches = (chord: ParsedChord, key: KeyMatch): boolean => {
-	if (chord.key === "tab" && key.name === "i" && key.ctrl && !key.shift && !key.meta) {
-		return true
-	}
-	if (chord.key !== key.name) return false
-	if (chord.shift !== Boolean(key.shift)) return false
-	if (chord.ctrl !== Boolean(key.ctrl)) return false
-	if (chord.meta !== Boolean(key.meta)) return false
-	return true
-}
-
-/**
- * Return the first binding that (a) is enabled for `ctx` and (b) has a key
- * that matches `key`. Runs the binding's action and returns it. Returns null
- * if nothing matched.
- */
-export const dispatch = <C>(
-	bindings: readonly KeyBinding<C>[],
-	ctx: C,
-	key: KeyMatch,
-): KeyBinding<C> | null => {
-	for (const binding of bindings) {
-		if (binding.when && !binding.when(ctx)) continue
-		for (const raw of binding.keys) {
-			if (chordMatches(parseChord(raw), key)) {
-				binding.run(ctx)
-				return binding
-			}
-		}
-	}
-	return null
-}