@carlesandres/house 0.3.0

package/src/HelpOverlay.tsx

@@ -0,0 +1,130 @@
+/**
+ * HelpOverlay — modal panel listing the keymap.
+ *
+ * Renders absolute-positioned over the rest of the UI. Iterates the
+ * KeyBinding[] array directly; there is no separate hand-written list of
+ * keys — the dispatcher and the help text are the same source of truth.
+ */
+
+import type { KeyBinding } from "./keymap/keymap.ts"
+import { colors } from "./theme/colors.ts"
+
+export interface HelpOverlayProps<C> {
+	readonly bindings: readonly KeyBinding<C>[]
+	readonly viewportWidth: number
+	readonly viewportHeight: number
+}
+
+const formatKeys = (keys: readonly string[]): string => keys.join(", ")
+
+interface Row {
+	readonly key: string
+	readonly text: string
+	readonly kind: "header" | "binding" | "spacer" | "footer"
+}
+
+const buildRows = <C,>(bindings: readonly KeyBinding<C>[]): Row[] => {
+	const order: string[] = []
+	const grouped = new Map<string, KeyBinding<C>[]>()
+	for (const b of bindings) {
+		if (!b.group) continue
+		if (!grouped.has(b.group)) {
+			grouped.set(b.group, [])
+			order.push(b.group)
+		}
+		grouped.get(b.group)!.push(b)
+	}
+
+	// Width of the keys column: longest formatted-keys string across all
+	// shown bindings, plus a small gap before descriptions.
+	let keyColumn = 0
+	for (const list of grouped.values()) {
+		for (const b of list) keyColumn = Math.max(keyColumn, formatKeys(b.keys).length)
+	}
+	const gap = 2
+	const padTo = keyColumn + gap
+
+	const rows: Row[] = []
+	for (let i = 0; i < order.length; i++) {
+		const group = order[i]!
+		// A spacer before *every* group, including the first. Without one
+		// before the first, opentui collapses the header onto the first
+		// binding row — appears to be an interaction between the title
+		// border and the first child of a padded column.
+		rows.push({ key: `spacer-before-${group}`, text: " ", kind: "spacer" })
+		rows.push({ key: `header-${group}`, text: group, kind: "header" })
+		for (const b of grouped.get(group)!) {
+			rows.push({
+				key: `binding-${b.id}`,
+				text: `  ${formatKeys(b.keys).padEnd(padTo)}${b.description}`,
+				kind: "binding",
+			})
+		}
+	}
+	rows.push({ key: "spacer-footer", text: " ", kind: "spacer" })
+	rows.push({ key: "footer", text: "press ? or esc to dismiss", kind: "footer" })
+	return rows
+}
+
+export const HelpOverlay = <C,>({
+	bindings,
+	viewportWidth,
+	viewportHeight,
+}: HelpOverlayProps<C>) => {
+	const rows = buildRows(bindings)
+
+	const overlayWidth = Math.min(viewportWidth - 4, 64)
+	const desiredHeight = rows.length + 2 // border top + bottom
+	const overlayHeight = Math.min(viewportHeight - 4, desiredHeight + 2) // +2 for vertical padding
+	const left = Math.max(0, Math.floor((viewportWidth - overlayWidth) / 2))
+	const top = Math.max(0, Math.floor((viewportHeight - overlayHeight) / 2))
+
+	return (
+		<box
+			position="absolute"
+			left={left}
+			top={top}
+			width={overlayWidth}
+			height={overlayHeight}
+			zIndex={10}
+			title=" Help "
+			titleAlignment="left"
+			style={{
+				border: true,
+				borderColor: colors.borderActive,
+				padding: 1,
+				flexDirection: "column",
+				backgroundColor: colors.surface,
+			}}
+		>
+			{rows.map((row) => {
+				switch (row.kind) {
+					case "header":
+						return (
+							<text
+								key={row.key}
+								wrapMode="none"
+								content={row.text}
+								style={{ fg: colors.borderActive, attributes: 1 /* bold */ }}
+							/>
+						)
+					case "footer":
+						return (
+							<text
+								key={row.key}
+								wrapMode="none"
+								content={row.text}
+								style={{ fg: colors.textMuted }}
+							/>
+						)
+					case "spacer":
+						return <text key={row.key} content=" " />
+					case "binding":
+						return (
+							<text key={row.key} wrapMode="none" content={row.text} style={{ fg: colors.text }} />
+						)
+				}
+			})}
+		</box>
+	)
+}

package/src/cli/argv.ts

@@ -0,0 +1,106 @@
+import { themeDefinitions } from "../theme/registry.ts"
+
+export interface ParsedArgs {
+	/** First positional argument, or null if none was given. */
+	readonly path: string | null
+	/** Value of `--theme <id>`, or null. Validated by the boot layer against the registry. */
+	readonly theme: string | null
+	/** Value of `--tone dark|light`, or null. Validated by the boot layer. */
+	readonly tone: string | null
+	/** Value of `--width <N>`, or null. Validated by the boot layer (must be a positive integer). */
+	readonly width: string | null
+	/** True when `--all` was passed: include hidden + gitignored files in discovery. */
+	readonly all: boolean
+	/** Value of `--sort <mode>` (`dirs-first` or `files-first`), or null. Validated by the boot layer. */
+	readonly sort: string | null
+	/** True when `--serve` was passed: serve the given file as HTML, skip TUI. */
+	readonly serve: boolean
+	/** Value of `--port <N>`, or null. Validated by the boot layer. */
+	readonly port: string | null
+	/** True when `--help` was passed. */
+	readonly help: boolean
+	/** True when `--version` was passed. */
+	readonly version: boolean
+}
+
+/**
+ * Minimal argv parser.
+ *
+ * Does not validate flag values — boot layers do, so error messages can
+ * reference domain knowledge (registered themes, valid integer ranges)
+ * without coupling the parser to it.
+ */
+export const parseArgv = (argv: readonly string[]): ParsedArgs => {
+	let path: string | null = null
+	let theme: string | null = null
+	let tone: string | null = null
+	let width: string | null = null
+	let all = false
+	let sort: string | null = null
+	let serve = false
+	let port: string | null = null
+	let help = false
+	let version = false
+
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]!
+		switch (arg) {
+			case "--theme":
+				theme = argv[i + 1] ?? null
+				i++
+				continue
+			case "--tone":
+				tone = argv[i + 1] ?? null
+				i++
+				continue
+			case "--width":
+				width = argv[i + 1] ?? null
+				i++
+				continue
+			case "--all":
+				all = true
+				continue
+			case "--sort":
+				sort = argv[i + 1] ?? null
+				i++
+				continue
+			case "--serve":
+				serve = true
+				continue
+			case "--port":
+				port = argv[i + 1] ?? null
+				i++
+				continue
+			case "--help":
+			case "-h":
+				help = true
+				continue
+			case "--version":
+			case "-v":
+				version = true
+				continue
+		}
+		if (path === null && !arg.startsWith("-")) {
+			path = arg
+		}
+	}
+
+	return { path, theme, tone, width, all, sort, serve, port, help, version }
+}
+
+const themeList = themeDefinitions.map((t) => t.id).join(", ")
+
+export const usage = `usage: house [path] [options]
+
+  path           file or directory; defaults to the current directory
+
+options:
+  --theme <id>   color theme: ${themeList} (default: opencode)
+  --tone <mode>  dark or light (default: dark)
+  --width <N>    cap rendered markdown width at N columns
+  --all          include hidden and gitignored files in discovery
+  --sort <mode>  sidebar order: dirs-first (default) or files-first
+  --serve        serve the given file as HTML in the browser (skips TUI)
+  --port <N>     port for --serve (default: OS-assigned)
+  -h, --help     show this help and exit
+  -v, --version  print version and exit`

package/src/discovery/filter.ts

@@ -0,0 +1,56 @@
+/**
+ * Fuzzy filter for the sidebar.
+ *
+ * Matching: case-insensitive subsequence on `relativePath`. A query "drm"
+ * matches "docs/readme.md". Scoring (higher is better):
+ *   - +10 for a match at the start of the string or right after `/`
+ *     (word boundary — what the user typed lines up with a path segment)
+ *   - +5 when the current match is adjacent to the previous one
+ *     (consecutive runs read as "drm" matching the literal substring)
+ *   - +1 otherwise
+ *
+ * The scorer is intentionally tiny — the only goal is to surface the
+ * "obvious" match for short queries against a few hundred paths. A full
+ * fzf-style scorer (with bonuses for camelCase, separators, etc.) is
+ * deferred until the simple version proves insufficient.
+ */
+
+import type { FileEntry } from "./walk.ts"
+
+export const fuzzyScore = (query: string, target: string): number | null => {
+	if (query.length === 0) return 0
+	const q = query.toLowerCase()
+	const t = target.toLowerCase()
+	let qi = 0
+	let score = 0
+	let lastMatch = -2
+	for (let i = 0; i < t.length && qi < q.length; i++) {
+		if (t[i] !== q[qi]) continue
+		const isWordStart = i === 0 || t[i - 1] === "/"
+		score += isWordStart ? 10 : 1
+		if (lastMatch === i - 1) score += 5
+		lastMatch = i
+		qi++
+	}
+	if (qi < q.length) return null
+	return score
+}
+
+/**
+ * Filter and re-rank a file list by a query. Empty query returns the input
+ * unchanged (preserves the discovery sort order). Non-empty query keeps
+ * matches only, sorted by score desc; ties fall back to the input order so
+ * the discovery sort still leaks through.
+ */
+export const filterFiles = (files: readonly FileEntry[], query: string): readonly FileEntry[] => {
+	if (query.length === 0) return files
+	const scored: { file: FileEntry; score: number; index: number }[] = []
+	for (let i = 0; i < files.length; i++) {
+		const file = files[i]!
+		const score = fuzzyScore(query, file.relativePath)
+		if (score === null) continue
+		scored.push({ file, score, index: i })
+	}
+	scored.sort((a, b) => b.score - a.score || a.index - b.index)
+	return scored.map((s) => s.file)
+}

package/src/discovery/walk.ts

@@ -0,0 +1,143 @@
+import { readdir, readFile } from "node:fs/promises"
+import { extname, join, relative, resolve } from "node:path"
+import { Data, Effect } from "effect"
+import ignore, { type Ignore } from "ignore"
+
+export interface FileEntry {
+	/** Absolute path on disk. */
+	readonly path: string
+	/** Path relative to the discovery root, with forward slashes. */
+	readonly relativePath: string
+	/** File basename. */
+	readonly name: string
+}
+
+export type SortOrder = "dirs-first" | "files-first"
+
+export interface WalkOptions {
+	/** Include hidden files and gitignored entries. Hard skips still apply. */
+	readonly all?: boolean
+	/** Group order within each directory. Default `dirs-first`. */
+	readonly sort?: SortOrder
+}
+
+export class DiscoveryError extends Data.TaggedError("DiscoveryError")<{
+	readonly root: string
+	readonly cause: unknown
+}> {}
+
+const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".mdx"])
+const HARD_SKIP_DIRS = new Set(["node_modules", ".git", ".venv"])
+
+interface IgnoreLevel {
+	readonly dir: string
+	readonly ig: Ignore
+}
+
+const isIgnored = (
+	entryPath: string,
+	isDirectory: boolean,
+	levels: readonly IgnoreLevel[],
+): boolean => {
+	for (const { dir, ig } of levels) {
+		const rel = relative(dir, entryPath)
+		if (!rel || rel.startsWith("..")) continue
+		const candidate = isDirectory ? `${rel}/` : rel
+		if (ig.ignores(candidate)) return true
+	}
+	return false
+}
+
+const tryLoadGitignore = async (dir: string): Promise<Ignore | null> => {
+	try {
+		const content = await readFile(join(dir, ".gitignore"), "utf8")
+		return ignore().add(content)
+	} catch {
+		return null
+	}
+}
+
+const sortEntries = <T extends { name: string; isDirectory: () => boolean }>(
+	entries: readonly T[],
+	order: SortOrder,
+): T[] =>
+	[...entries].sort((a, b) => {
+		const aDir = a.isDirectory()
+		const bDir = b.isDirectory()
+		if (aDir !== bDir) {
+			if (order === "files-first") return aDir ? 1 : -1
+			return aDir ? -1 : 1
+		}
+		return a.name.localeCompare(b.name)
+	})
+
+const walkDir = async (
+	dirPath: string,
+	rootPath: string,
+	parentLevels: readonly IgnoreLevel[],
+	results: FileEntry[],
+	opts: { all: boolean; sort: SortOrder },
+): Promise<void> => {
+	let levels = parentLevels
+	if (!opts.all) {
+		const ig = await tryLoadGitignore(dirPath)
+		if (ig) levels = [...parentLevels, { dir: dirPath, ig }]
+	}
+
+	const raw = await readdir(dirPath, { withFileTypes: true })
+	for (const entry of sortEntries(raw, opts.sort)) {
+		// Never follow symlinks — cycle hazard, and a markdown reader doesn't
+		// need them. May be relaxed (files only) in a later iteration.
+		if (entry.isSymbolicLink()) continue
+
+		const entryPath = join(dirPath, entry.name)
+
+		if (entry.isDirectory()) {
+			if (HARD_SKIP_DIRS.has(entry.name)) continue
+			if (!opts.all && entry.name.startsWith(".")) continue
+			if (!opts.all && isIgnored(entryPath, true, levels)) continue
+			await walkDir(entryPath, rootPath, levels, results, opts)
+			continue
+		}
+
+		if (!entry.isFile()) continue
+		if (!opts.all && entry.name.startsWith(".")) continue
+		if (!MARKDOWN_EXTENSIONS.has(extname(entry.name).toLowerCase())) continue
+		if (!opts.all && isIgnored(entryPath, false, levels)) continue
+
+		results.push({
+			path: entryPath,
+			relativePath: relative(rootPath, entryPath),
+			name: entry.name,
+		})
+	}
+}
+
+/**
+ * Walk a directory tree and return markdown files in a stable order.
+ *
+ * Rules (see DESIGN.md §6):
+ * - Extensions: `.md`, `.markdown`, `.mdx`.
+ * - Hard skips (always): `node_modules`, `.git`, `.venv`.
+ * - Hidden files/dirs (leading `.`) skipped unless `all: true`.
+ * - `.gitignore` honored, including nested `.gitignore` files.
+ * - Symlinks not followed.
+ * - Sort: alphabetical within each group; directories before files
+ *   (`dirs-first`, default) or files before directories (`files-first`).
+ */
+export const walk = (
+	root: string,
+	options: WalkOptions = {},
+): Effect.Effect<readonly FileEntry[], DiscoveryError> =>
+	Effect.tryPromise({
+		try: async () => {
+			const absRoot = resolve(root)
+			const results: FileEntry[] = []
+			await walkDir(absRoot, absRoot, [], results, {
+				all: options.all ?? false,
+				sort: options.sort ?? "dirs-first",
+			})
+			return results
+		},
+		catch: (cause) => new DiscoveryError({ root, cause }),
+	})

package/src/index.tsx

@@ -0,0 +1,265 @@
+#!/usr/bin/env bun
+/**
+ * house — entry point.
+ *
+ * Reads a markdown file path from argv and renders it via opentui's built-in
+ * <markdown> component inside a scrollbox. q / ctrl+c to quit.
+ *
+ * Discovery, sidebar, theming, and richer Effect wiring all land after this.
+ */
+
+import { stat } from "node:fs/promises"
+import { createCliRenderer, SyntaxStyle } from "@opentui/core"
+import { createRoot, useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react"
+import { RegistryProvider, useAtomSet, useAtomValue } from "@effect/atom-react"
+import { Effect } from "effect"
+import { useMemo } from "react"
+import pkg from "../package.json" with { type: "json" }
+import { Browser } from "./Browser.tsx"
+import { parseArgv, usage } from "./cli/argv.ts"
+import { walk, type SortOrder } from "./discovery/walk.ts"
+import { readFileText } from "./io/readFile.ts"
+import { openInBrowser } from "./serve/openBrowser.ts"
+import { startServer } from "./serve/server.ts"
+import { colors, setActiveTheme } from "./theme/colors.ts"
+import { themeAtom, type ThemeState } from "./theme/atom.ts"
+import { getThemeDefinition, isThemeId, themeDefinitions } from "./theme/registry.ts"
+
+export interface AppProps {
+	/** Markdown source to render. */
+	readonly content: string
+	/** Optional title shown in the frame border. Defaults to a generic label. */
+	readonly title?: string
+	/** Cap the rendered markdown's width at N columns (left-aligned). Null = fill the pane. */
+	readonly maxWidth?: number | null
+	/** Override quit behavior. Tests pass a spy; the binary uses the default. */
+	readonly onQuit?: () => void
+}
+
+export const App = ({ content, title = "house", maxWidth = null, onQuit }: AppProps) => {
+	const renderer = useRenderer()
+	const { width, height } = useTerminalDimensions()
+	const theme = useAtomValue(themeAtom)
+	const setTheme = useAtomSet(themeAtom)
+	const syntaxStyle = useMemo(() => SyntaxStyle.fromStyles(colors.syntax), [theme])
+
+	const cycleTheme = (delta: 1 | -1) => {
+		const idx = themeDefinitions.findIndex((d) => d.id === theme.id)
+		const next = themeDefinitions[(idx + delta + themeDefinitions.length) % themeDefinitions.length]
+		if (!next) return
+		setActiveTheme(next, theme.tone)
+		setTheme({ id: next.id, tone: theme.tone })
+	}
+
+	const toggleTone = () => {
+		const nextTone = theme.tone === "dark" ? "light" : "dark"
+		const def = getThemeDefinition(theme.id)
+		if (def) setActiveTheme(def, nextTone)
+		setTheme({ id: theme.id, tone: nextTone })
+	}
+
+	useKeyboard((key) => {
+		if (key.name === "q" || (key.ctrl && key.name === "c")) {
+			if (onQuit) {
+				onQuit()
+				return
+			}
+			renderer?.destroy()
+			process.exit(0)
+		}
+		if (key.name === "t" && !key.shift) cycleTheme(1)
+		if (key.name === "t" && key.shift) cycleTheme(-1)
+		if (key.name === "l" && key.shift) toggleTone()
+	})
+
+	return (
+		<box style={{ width, height, flexDirection: "column", backgroundColor: colors.background }}>
+			<box
+				title={` ${title} `}
+				titleAlignment="left"
+				style={{
+					border: true,
+					borderColor: colors.border,
+					padding: 1,
+					flexGrow: 1,
+					flexShrink: 1,
+					backgroundColor: colors.background,
+				}}
+			>
+				<scrollbox
+					style={{
+						scrollY: true,
+						scrollX: false,
+						flexGrow: 1,
+						flexShrink: 1,
+						backgroundColor: colors.background,
+					}}
+					focused
+				>
+					<markdown
+						content={content}
+						syntaxStyle={syntaxStyle}
+						fg={colors.text}
+						bg={colors.background}
+						conceal
+						style={{ width: maxWidth ?? "100%" }}
+					/>
+				</scrollbox>
+			</box>
+		</box>
+	)
+}
+
+if (import.meta.main) {
+	const args = parseArgv(Bun.argv.slice(2))
+
+	if (args.help) {
+		console.log(usage)
+		process.exit(0)
+	}
+	if (args.version) {
+		console.log(pkg.version)
+		process.exit(0)
+	}
+
+	const themeId = args.theme ?? "opencode"
+	if (!isThemeId(themeId)) {
+		const known = themeDefinitions.map((t) => t.id).join(", ")
+		console.error(`house: unknown theme "${themeId}". Known: ${known}`)
+		process.exit(2)
+	}
+	const tone = args.tone ?? "dark"
+	if (tone !== "dark" && tone !== "light") {
+		console.error(`house: --tone must be "dark" or "light", got "${tone}"`)
+		process.exit(2)
+	}
+	const themeDef = getThemeDefinition(themeId)
+	if (themeDef === undefined) {
+		console.error(`house: unknown theme "${themeId}"`)
+		process.exit(2)
+	}
+	setActiveTheme(themeDef, tone)
+
+	let maxWidth: number | null = null
+	if (args.width !== null) {
+		const n = Number.parseInt(args.width, 10)
+		if (!Number.isFinite(n) || n <= 0) {
+			console.error(`house: --width must be a positive integer, got "${args.width}"`)
+			process.exit(2)
+		}
+		maxWidth = n
+	}
+
+	const target = args.path ?? "."
+
+	if (args.serve) {
+		let stats: Awaited<ReturnType<typeof stat>>
+		try {
+			stats = await stat(target)
+		} catch (err) {
+			console.error(`house: cannot access ${target}: ${String(err)}`)
+			process.exit(1)
+		}
+		if (stats.isDirectory()) {
+			console.error(`house: --serve requires a file, got directory ${target}`)
+			process.exit(2)
+		}
+		let port = 0
+		if (args.port !== null) {
+			const n = Number.parseInt(args.port, 10)
+			if (!Number.isFinite(n) || n < 0 || n > 65535) {
+				console.error(`house: --port must be 0-65535, got "${args.port}"`)
+				process.exit(2)
+			}
+			port = n
+		}
+		const handle = startServer({ path: target, port })
+		console.log(`house serving ${target} at ${handle.url}`)
+		console.log("press ctrl+c to stop")
+		openInBrowser(handle.url)
+		const shutdown = async () => {
+			await handle.stop()
+			process.exit(0)
+		}
+		process.on("SIGINT", shutdown)
+		process.on("SIGTERM", shutdown)
+		// Bun.serve keeps the event loop alive until stop().
+	} else {
+		let sort: SortOrder = "dirs-first"
+		if (args.sort !== null) {
+			if (args.sort !== "dirs-first" && args.sort !== "files-first") {
+				console.error(`house: --sort must be "dirs-first" or "files-first", got "${args.sort}"`)
+				process.exit(2)
+			}
+			sort = args.sort
+		}
+		await runTui({ target, themeId, tone, maxWidth, all: args.all, sort })
+	}
+}
+
+interface TuiBootOptions {
+	readonly target: string
+	readonly themeId: string
+	readonly tone: "dark" | "light"
+	readonly maxWidth: number | null
+	readonly all: boolean
+	readonly sort: SortOrder
+}
+
+async function runTui({
+	target,
+	themeId,
+	tone,
+	maxWidth,
+	all,
+	sort,
+}: TuiBootOptions): Promise<void> {
+	let stats: Awaited<ReturnType<typeof stat>>
+	try {
+		stats = await stat(target)
+	} catch (err) {
+		console.error(`house: cannot access ${target}: ${String(err)}`)
+		process.exit(1)
+	}
+
+	const renderer = await createCliRenderer({ exitOnCtrlC: false })
+	const initialTheme: ThemeState = { id: themeId, tone }
+
+	if (stats.isDirectory()) {
+		const files = await Effect.runPromise(
+			walk(target, { all, sort }).pipe(
+				Effect.tapError((err) =>
+					Effect.sync(() => {
+						console.error(`house: cannot walk ${target}: ${String(err.cause)}`)
+					}),
+				),
+			),
+		).catch(() => {
+			process.exit(1)
+		})
+		if (!Array.isArray(files)) process.exit(1)
+		createRoot(renderer).render(
+			<RegistryProvider initialValues={[[themeAtom, initialTheme]]}>
+				<Browser files={files} title={target} maxWidth={maxWidth} />
+			</RegistryProvider>,
+		)
+	} else {
+		const content = await Effect.runPromise(
+			readFileText(target).pipe(
+				Effect.tapError((err) =>
+					Effect.sync(() => {
+						console.error(`house: cannot read ${err.path}: ${String(err.cause)}`)
+					}),
+				),
+			),
+		).catch(() => {
+			process.exit(1)
+		})
+		if (typeof content !== "string") process.exit(1)
+		createRoot(renderer).render(
+			<RegistryProvider initialValues={[[themeAtom, initialTheme]]}>
+				<App content={content} title={target} maxWidth={maxWidth} />
+			</RegistryProvider>,
+		)
+	}
+}