@carlesandres/house 0.3.1 → 0.4.1

package/src/index.tsx

@@ -10,25 +10,31 @@
 
 import { stat } from "node:fs/promises"
 import { createCliRenderer, SyntaxStyle } from "@opentui/core"
+import type { BorderSides } 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 { Cause, Duration, Effect, Fiber, Stream } from "effect"
+import { useEffect, useMemo, useRef, useState } 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 { defaultConfigPath, formatConfigError, loadConfig } from "./config/load.ts"
+import { walk, type FileEntry, type SortOrder } from "./discovery/walk.ts"
+import { Header } from "./Header.tsx"
 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"
+import { getThemeDefinition, themeDefinitions } from "./theme/registry.ts"
+import { formatQuitNotice } from "./update/notice.ts"
+import { currentUpdateInfo, startUpdateProbe } from "./update/runtime.ts"
+import { useUpdateNotice } from "./update/useUpdateNotice.ts"
 
 export interface AppProps {
 	/** Markdown source to render. */
 	readonly content: string
-	/** Optional title shown in the frame border. Defaults to a generic label. */
+	/** Optional title shown in the header's current-file slot. 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
@@ -36,6 +42,80 @@ export interface AppProps {
 	readonly onQuit?: () => void
 }
 
+/**
+ * DiscoverShell — owns the streaming walk for directory mode. Mounts Browser
+ * immediately with `files=[]` and pushes entries as the stream emits.
+ *
+ * Batching: `Stream.groupedWithin(64, 60ms)` coalesces bursts so we don't
+ * trigger one React render per file. Tuned by feel — small enough that
+ * results still feel live on tiny trees, large enough to keep render
+ * frequency sane on big ones. Revisit if profiling says otherwise.
+ *
+ * Cancellation: the walk runs on a forked fiber; unmount interrupts it.
+ * `Quit` in Browser tears down the renderer and exits, which propagates
+ * naturally — the cleanup effect still fires before process.exit completes.
+ */
+export type SidebarMode = "auto" | "on" | "off"
+
+interface DiscoverShellProps {
+	readonly target: string
+	readonly all: boolean
+	readonly sort: SortOrder
+	readonly mdx: boolean
+	readonly maxWidth: number | null
+	readonly sidebarMode: SidebarMode
+}
+
+const DiscoverShell = ({ target, all, sort, mdx, maxWidth, sidebarMode }: DiscoverShellProps) => {
+	const updateNotice = useUpdateNotice()
+	const [files, setFiles] = useState<readonly FileEntry[]>([])
+	const [scanning, setScanning] = useState<boolean>(true)
+	const [scanError, setScanError] = useState<string | null>(null)
+	// Files arrive in a ref-tracked count so the status string can show
+	// "indexing… N" even when React hasn't yet flushed the latest setFiles.
+	const countRef = useRef(0)
+
+	useEffect(() => {
+		const program = walk(target, { all, sort, mdx }).pipe(
+			Stream.groupedWithin(64, Duration.millis(60)),
+			Stream.runForEach((chunk) =>
+				Effect.sync(() => {
+					const arr = Array.from(chunk)
+					if (arr.length === 0) return
+					countRef.current += arr.length
+					setFiles((prev) => [...prev, ...arr])
+				}),
+			),
+			Effect.matchCauseEffect({
+				onSuccess: () => Effect.sync(() => setScanning(false)),
+				onFailure: (cause) =>
+					Effect.sync(() => {
+						// Interruption is the normal teardown path — don't surface it.
+						if (Cause.hasInterrupts(cause)) return
+						setScanError(`scan failed: ${Cause.pretty(cause)}`)
+						setScanning(false)
+					}),
+			}),
+		)
+		const fiber = Effect.runFork(program)
+		return () => {
+			Effect.runFork(Fiber.interrupt(fiber))
+		}
+	}, [target, all, sort, mdx])
+
+	const discoveryStatus = scanError ?? (scanning ? `indexing… ${countRef.current}` : null)
+
+	return (
+		<Browser
+			files={files}
+			maxWidth={maxWidth}
+			discoveryStatus={discoveryStatus}
+			sidebarMode={sidebarMode}
+			updateNotice={updateNotice}
+		/>
+	)
+}
+
 export const App = ({ content, title = "house", maxWidth = null, onQuit }: AppProps) => {
 	const renderer = useRenderer()
 	const { width, height } = useTerminalDimensions()
@@ -72,13 +152,14 @@ export const App = ({ content, title = "house", maxWidth = null, onQuit }: AppPr
 		if (key.name === "l" && key.shift) toggleTone()
 	})
 
+	const paneBorderSides: BorderSides[] = ["top", "bottom"]
+
 	return (
 		<box style={{ width, height, flexDirection: "column", backgroundColor: colors.background }}>
+			<Header width={width} currentFile={title} />
 			<box
-				title={` ${title} `}
-				titleAlignment="left"
 				style={{
-					border: true,
+					border: paneBorderSides,
 					borderColor: colors.border,
 					padding: 1,
 					flexGrow: 1,
@@ -110,6 +191,8 @@ export const App = ({ content, title = "house", maxWidth = null, onQuit }: AppPr
 	)
 }
 
+let updateExitHookRegistered = false
+
 if (import.meta.main) {
 	const args = parseArgv(Bun.argv.slice(2))
 
@@ -121,20 +204,29 @@ if (import.meta.main) {
 		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)
+	if (args.configPath) {
+		console.log(defaultConfigPath())
+		process.exit(0)
 	}
-	const tone = args.tone ?? "dark"
-	if (tone !== "dark" && tone !== "light") {
-		console.error(`house: --tone must be "dark" or "light", got "${tone}"`)
+
+	const config = await Effect.runPromise(
+		loadConfig({
+			cli: {
+				theme: args.theme,
+				tone: args.tone,
+				// --no-mdx is a one-way override: present means "off". When
+				// absent, fall through to env/file/default.
+				mdx: args.noMdx ? false : null,
+			},
+		}),
+	).catch((err: unknown) => {
+		console.error(`house: ${formatConfigError(err)}`)
 		process.exit(2)
-	}
+	})
+	const { theme: themeId, tone, mdx } = config
 	const themeDef = getThemeDefinition(themeId)
 	if (themeDef === undefined) {
+		// Unreachable: Config.schema validated themeId against themeDefinitions.
 		console.error(`house: unknown theme "${themeId}"`)
 		process.exit(2)
 	}
@@ -193,7 +285,25 @@ if (import.meta.main) {
 			}
 			sort = args.sort
 		}
-		await runTui({ target, themeId, tone, maxWidth, all: args.all, sort })
+		let sidebarMode: SidebarMode = "auto"
+		if (args.sidebar !== null) {
+			if (args.sidebar !== "auto" && args.sidebar !== "on" && args.sidebar !== "off") {
+				console.error(`house: --sidebar must be "auto", "on", or "off", got "${args.sidebar}"`)
+				process.exit(2)
+			}
+			sidebarMode = args.sidebar
+		}
+		await runTui({
+			target,
+			themeId,
+			tone,
+			maxWidth,
+			all: args.all,
+			sort,
+			mdx,
+			sidebarMode,
+			updateCheck: !args.noUpdateCheck,
+		})
 	}
 }
 
@@ -204,6 +314,11 @@ interface TuiBootOptions {
 	readonly maxWidth: number | null
 	readonly all: boolean
 	readonly sort: SortOrder
+	readonly mdx: boolean
+	readonly sidebarMode: SidebarMode
+	/** Run the npm-registry probe and surface the "update available" notice.
+	 *  False suppresses both the toast and the quit-time print. */
+	readonly updateCheck: boolean
 }
 
 async function runTui({
@@ -213,6 +328,9 @@ async function runTui({
 	maxWidth,
 	all,
 	sort,
+	mdx,
+	sidebarMode,
+	updateCheck,
 }: TuiBootOptions): Promise<void> {
 	let stats: Awaited<ReturnType<typeof stat>>
 	try {
@@ -222,25 +340,38 @@ async function runTui({
 		process.exit(1)
 	}
 
+	if (updateCheck) {
+		// Fire the npm-registry probe in the background. Result lands in a
+		// module singleton; the React tree picks it up via `useUpdateNotice`
+		// for the footer toast, and the 'exit' hook below reads it
+		// synchronously for the scrollback print. Failures are silent — this
+		// whole feature is opportunistic.
+		startUpdateProbe(pkg.name, pkg.version)
+		// Register once per process. Multiple 'exit' listeners would print
+		// the notice multiple times if runTui were ever re-entered.
+		if (!updateExitHookRegistered) {
+			updateExitHookRegistered = true
+			process.on("exit", () => {
+				const info = currentUpdateInfo()
+				if (info) process.stderr.write(formatQuitNotice(info))
+			})
+		}
+	}
+
 	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} />
+				<DiscoverShell
+					target={target}
+					all={all}
+					sort={sort}
+					mdx={mdx}
+					maxWidth={maxWidth}
+					sidebarMode={sidebarMode}
+				/>
 			</RegistryProvider>,
 		)
 	} else {

package/src/keymap/browser.ts

@@ -11,14 +11,18 @@ export type BrowserFocus = "sidebar" | "reader"
 export interface BrowserCtx {
 	readonly files: readonly FileEntry[]
 	readonly focus: BrowserFocus
-	readonly sidebarVisible: boolean
+	/** User's sticky sidebar preference. Visibility is `shown || focus==="sidebar"`. */
+	readonly sidebarShown: boolean
 	readonly helpVisible: boolean
 	readonly filterOpen: boolean
+	readonly paletteOpen: boolean
 	readonly setFocus: (next: BrowserFocus | ((prev: BrowserFocus) => BrowserFocus)) => void
 	readonly setSelectedIndex: (updater: (prev: number) => number) => void
-	readonly setSidebarVisible: (updater: (prev: boolean) => boolean) => void
+	/** Toggle `shown` and adjust focus per DESIGN.md §7.1 (see s-behavior table). */
+	readonly toggleShown: () => void
 	readonly setHelpVisible: (updater: (prev: boolean) => boolean) => void
 	readonly openFilter: () => void
+	readonly openPalette: () => void
 	readonly cycleTheme: (delta: 1 | -1) => void
 	readonly toggleTone: () => void
 	readonly quit: () => void
@@ -37,7 +41,8 @@ const stepBy = (c: BrowserCtx, delta: number) =>
 	c.setSelectedIndex((i) => clamp(i + delta, 0, lastIndex(c)))
 
 const inSidebar = (c: BrowserCtx) => c.focus === "sidebar"
-const inSidebarFilterClosed = (c: BrowserCtx) => inSidebar(c) && !c.filterOpen
+const filterClosed = (c: BrowserCtx) => !c.filterOpen
+const paletteClosed = (c: BrowserCtx) => !c.paletteOpen
 const inReader = (c: BrowserCtx) => c.focus === "reader"
 const inSidebarWithFiles = (c: BrowserCtx) => inSidebar(c) && haveFiles(c)
 const inReaderWithFiles = (c: BrowserCtx) => inReader(c) && haveFiles(c)
@@ -66,13 +71,7 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		description: "Toggle sidebar visibility",
 		hint: "sidebar",
 		keys: ["s"],
-		run: (c) => {
-			const willHide = c.sidebarVisible
-			c.setSidebarVisible((v) => !v)
-			// When hiding the sidebar, move focus to the reader so input has a
-			// target. When revealing it, move focus back to the sidebar.
-			c.setFocus(willHide ? "reader" : "sidebar")
-		},
+		run: (c) => c.toggleShown(),
 	},
 	{
 		id: "help.toggle",
@@ -88,9 +87,25 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		description: "Filter files (fuzzy match on path)",
 		hint: "filter",
 		keys: ["/"],
-		when: inSidebarFilterClosed,
+		// 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: "palette.open",
+		group: "Global",
+		description: "Command palette",
+		hint: "palette",
+		keys: ["ctrl+p"],
+		// Filter swallows ctrl+p as a typed character in its own branch, so this
+		// `when` only matters when the palette is already open (which it
+		// shouldn't re-open). #70 Q2 — fires from everywhere except the filter,
+		// closes help on its way in (handled in Browser.tsx).
+		when: paletteClosed,
+		run: (c) => c.openPalette(),
+	},
 	{
 		id: "serve.current",
 		group: "Global",

package/src/layout/resolve.ts

@@ -0,0 +1,60 @@
+/**
+ * Layout primitives for the two-pane shape (sidebar + reader).
+ *
+ * Visibility and width are decoupled (see DESIGN.md §7.1):
+ *   visible = shown || focus === "sidebar"
+ * Width is a pure function of viewport, independent of visibility:
+ *   resolveSidebarWidth(viewport, preferred)
+ *
+ * Both render code and key handlers consume these primitives — there is no
+ * parallel implementation living in JSX.
+ */
+
+/** Minimum useful sidebar width; below this, file rows truncate too aggressively. */
+export const SIDEBAR_MIN_WIDTH = 28
+/** Maximum sidebar width; beyond this, wasted whitespace on wide terminals. */
+export const SIDEBAR_MAX_WIDTH = 60
+/** Reader pane minimum; below this, prose wraps unpleasantly. */
+export const READER_MIN_WIDTH = 40
+/** Column gap painted between the two panes when both are inline. */
+export const DIVIDER_WIDTH = 1
+
+/**
+ * Continuous clamp. `preferred` is the user's desired width (until #13 lands,
+ * derived from viewport). The reader-min ceiling means the sidebar yields
+ * space rather than squeezing the reader below readability.
+ *
+ * Result is not clamped *up* to SIDEBAR_MIN when the viewport itself is too
+ * narrow to hold both panes — the caller decides whether to render at all
+ * (e.g. single-pane stack instead of inline). See `canFitInline`.
+ */
+export const resolveSidebarWidth = (viewport: number, preferred: number): number => {
+	const ceiling = viewport - DIVIDER_WIDTH - READER_MIN_WIDTH
+	const lower = Math.min(SIDEBAR_MIN_WIDTH, Math.max(0, ceiling))
+	const upper = Math.max(lower, ceiling)
+	return Math.max(lower, Math.min(upper, preferred))
+}
+
+/**
+ * Default preferred sidebar width, derived from viewport until persistent
+ * config (#13) provides a user-set value. Matches the previous inline math.
+ */
+export const defaultPreferredWidth = (viewport: number): number =>
+	Math.max(SIDEBAR_MIN_WIDTH, Math.min(SIDEBAR_MAX_WIDTH, Math.floor(viewport * 0.25)))
+
+/**
+ * True when an inline (side-by-side) layout still gives the reader at least
+ * READER_MIN_WIDTH. When false, the viewport is "narrow" and the UI runs in
+ * single-pane stack mode — sidebar OR reader fills the pane area, never both.
+ * See DESIGN.md §7.1.
+ */
+export const canFitInline = (viewport: number): boolean =>
+	viewport >= SIDEBAR_MIN_WIDTH + DIVIDER_WIDTH + READER_MIN_WIDTH
+
+/**
+ * Initial sidebar visibility for `--sidebar=auto`. Always true — every
+ * viewport now boots on the sidebar (narrow: as the single visible screen;
+ * wide: as the focused inline pane). `--sidebar=off` is the only way to
+ * boot directly into the reader.
+ */
+export const initialShownForAuto = (_viewport: number): boolean => true

package/src/theme/colors.ts

@@ -9,24 +9,60 @@ import type { ColorPalette, ResolvedTheme, ThemeDefinition, Tone } from "./types
  * - UI tokens map name-for-name where they overlap.
  * - `surface` ← `backgroundPanel`, `selectedBg` ← `backgroundElement`,
  *   `selectedBgInactive` ← `borderSubtle`.
- * - `textStrong` borrows `markdownStrong` (the brightest/most-emphasized
- *   text token in opencode's palette).
+ * - `textStrong` ← `primary` (opencode's convention for emphasized brand
+ *   text in UI chrome). Markdown rendering still reads `markdownStrong`
+ *   directly via the syntax map.
  * - `syntax` is a fully populated opentui tree-sitter scope map built from
  *   `markdown*` and `syntax*` tokens.
  */
-const buildPalette = (r: ResolvedTheme): ColorPalette => ({
-	background: r.background,
-	surface: r.backgroundPanel,
-	text: r.text,
-	textStrong: r.markdownStrong,
-	textMuted: r.textMuted,
-	border: r.border,
-	borderActive: r.borderActive,
-	selectedBg: r.backgroundElement,
-	selectedBgInactive: r.borderSubtle,
-	error: r.error,
-	syntax: buildSyntaxMap(r),
-})
+/** Relative luminance of a `#rrggbb` color (0..1). Sufficient for ordering
+ *  two near-neutral chrome colors — not a full WCAG contrast calculation.
+ *  Non-hex inputs fall back to 0.5 so the caller's ordering is a no-op. */
+const luminance = (hex: string): number => {
+	const m = /^#([0-9a-fA-F]{6})$/.exec(hex)
+	if (!m) return 0.5
+	const h = m[1]!
+	const r = parseInt(h.slice(0, 2), 16)
+	const g = parseInt(h.slice(2, 4), 16)
+	const b = parseInt(h.slice(4, 6), 16)
+	// Rec. 601 weighting — perceptual ordering, not the linearized WCAG variant.
+	return (0.299 * r + 0.587 * g + 0.114 * b) / 255
+}
+
+/** Pane chrome assumes the active/raised pane sits on the darker of the two
+ *  background tokens and the dim chrome on the lighter one. Most themes
+ *  define `background` darker than `backgroundPanel` and this is a no-op;
+ *  some (e.g. cursor) flip the polarity, in which case we swap so the
+ *  active-pane convention stays consistent across themes. */
+const orientChrome = (r: ResolvedTheme): { raised: string; dim: string } => {
+	const bg = r.background
+	const panel = r.backgroundPanel
+	return luminance(bg) <= luminance(panel) ? { raised: bg, dim: panel } : { raised: panel, dim: bg }
+}
+
+const buildPalette = (r: ResolvedTheme): ColorPalette => {
+	const { raised, dim } = orientChrome(r)
+	return {
+		background: raised,
+		surface: dim,
+		text: r.text,
+		textStrong: r.primary,
+		textMuted: r.textMuted,
+		border: r.border,
+		borderActive: r.borderActive,
+		selectedBg: r.backgroundElement,
+		selectedBgInactive: r.borderSubtle,
+		selectedListItemText: r.selectedListItemText,
+		primary: r.primary,
+		secondary: r.secondary,
+		accent: r.accent,
+		error: r.error,
+		warning: r.warning,
+		success: r.success,
+		info: r.info,
+		syntax: buildSyntaxMap(r),
+	}
+}
 
 const buildSyntaxMap = (r: ResolvedTheme): Record<string, StyleDefinitionInput> => {
 	const codeBg = r.backgroundPanel

package/src/theme/types.ts

@@ -97,7 +97,14 @@ export interface ColorPalette {
 	readonly borderActive: string
 	readonly selectedBg: string
 	readonly selectedBgInactive: string
+	readonly selectedListItemText: string
+	readonly primary: string
+	readonly secondary: string
+	readonly accent: string
 	readonly error: string
+	readonly warning: string
+	readonly success: string
+	readonly info: string
 	readonly syntax: Record<string, StyleDefinitionInput>
 }
 

package/src/update/cache.ts

@@ -0,0 +1,77 @@
+/**
+ * Update-check cache. Stores the last npm-registry probe result on disk so
+ * we hit the registry at most once per TTL window.
+ *
+ * Layout: `$XDG_CACHE_HOME/house/update-check.json` (fallback
+ * `~/.cache/house/update-check.json`). All IO failures are non-fatal — a
+ * missing or unparseable cache simply forces a fresh probe.
+ *
+ * Schema is intentionally minimal. `tarballOk` distinguishes "we saw the
+ * version and confirmed the tarball is downloadable" from "we saw the
+ * version but the CDN HEAD failed" — only the former gates the notice. A
+ * `false` entry forces a retry on the next launch rather than waiting out
+ * the TTL.
+ */
+
+import { dirname, join } from "node:path"
+import { homedir } from "node:os"
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises"
+
+export interface UpdateCacheRecord {
+	readonly checkedAt: number
+	readonly latestVersion: string
+	readonly tarballOk: boolean
+}
+
+export const cacheDir = (): string => {
+	const xdg = process.env.XDG_CACHE_HOME
+	if (xdg && xdg.length > 0) return join(xdg, "house")
+	return join(homedir(), ".cache", "house")
+}
+
+export const cachePath = (): string => join(cacheDir(), "update-check.json")
+
+export const readCache = async (path = cachePath()): Promise<UpdateCacheRecord | null> => {
+	try {
+		const raw = await readFile(path, "utf8")
+		const parsed = JSON.parse(raw) as unknown
+		if (typeof parsed !== "object" || parsed === null) return null
+		const r = parsed as Record<string, unknown>
+		if (
+			typeof r.checkedAt !== "number" ||
+			typeof r.latestVersion !== "string" ||
+			typeof r.tarballOk !== "boolean"
+		) {
+			return null
+		}
+		return {
+			checkedAt: r.checkedAt,
+			latestVersion: r.latestVersion,
+			tarballOk: r.tarballOk,
+		}
+	} catch {
+		return null
+	}
+}
+
+export const writeCache = async (record: UpdateCacheRecord, path = cachePath()): Promise<void> => {
+	// Atomic write: writeFile to a sibling tmp path, then rename. Rename is
+	// atomic on POSIX, so a process.exit() racing the writer either leaves
+	// the prior file intact or installs the new one fully — never a partial
+	// JSON blob that readCache would have to ignore.
+	const tmp = `${path}.${process.pid}.${Date.now()}.tmp`
+	try {
+		await mkdir(dirname(path), { recursive: true })
+		await writeFile(tmp, JSON.stringify(record), "utf8")
+		await rename(tmp, path)
+	} catch {
+		// Cache writes are best-effort. A read-only HOME or full disk should
+		// not break the app; we'll just re-probe on the next launch. Clean up
+		// the tmp file if writeFile partially succeeded but rename did not.
+		try {
+			await unlink(tmp)
+		} catch {
+			// best-effort
+		}
+	}
+}