@carlesandres/house 0.4.0 → 0.4.2

package/src/config/load.ts

@@ -18,39 +18,96 @@ import { themeDefinitions } from "../theme/registry.ts"
 export interface HouseConfig {
 	readonly theme: string
 	readonly tone: "dark" | "light"
+	readonly mdx: boolean
 }
 
 export interface CliOverrides {
 	readonly theme: string | null
 	readonly tone: string | null
+	readonly mdx: boolean | null
 }
 
 const DEFAULT_THEME = "opencode"
 const DEFAULT_TONE: "dark" | "light" = "dark"
+const DEFAULT_MDX = true
 
 const themeIds = themeDefinitions.map((t) => t.id)
 
 /**
  * Top-level keys the config file is allowed to set. Kept in sync by hand
  * with `schema` below — when adding a key, add it both places.
- * Used by `fileProvider` to reject typo'd keys (e.g. `them = "..."`) loudly
- * rather than silently falling back to defaults.
+ * Used by `fileProvider` to warn about unrecognized keys (with a
+ * did-you-mean hint when one is close) while still loading the rest.
  */
-const KNOWN_FILE_KEYS: ReadonlySet<string> = new Set(["theme", "tone"])
+const KNOWN_FILE_KEYS: ReadonlySet<string> = new Set(["theme", "tone", "mdx"])
 
 const schema = Config.all({
 	theme: Config.schema(Schema.Literals(themeIds), "theme"),
 	tone: Config.schema(Schema.Literals(["dark", "light"] as const), "tone"),
+	// Boolean stored as string literal because providers stringify values
+	// (TOML bools, env vars, CLI flags all flow through as text). Mapped to
+	// a real boolean in `loadConfig` below.
+	mdx: Config.schema(Schema.Literals(["true", "false"] as const), "mdx"),
 })
 
 const defaultsProvider = (): ConfigProvider.ConfigProvider =>
-	ConfigProvider.fromUnknown({ theme: DEFAULT_THEME, tone: DEFAULT_TONE })
+	ConfigProvider.fromUnknown({
+		theme: DEFAULT_THEME,
+		tone: DEFAULT_TONE,
+		mdx: String(DEFAULT_MDX),
+	})
+
+/**
+ * Levenshtein edit distance, capped at `cap` for early exit.
+ * Used only to suggest "did you mean X?" when a config key looks like a
+ * typo of a known one. Tiny inputs (≤ ~20 chars), so the naive O(n·m)
+ * fill is fine.
+ */
+const editDistance = (a: string, b: string, cap: number): number => {
+	if (Math.abs(a.length - b.length) > cap) return cap + 1
+	const prev: number[] = Array.from({ length: b.length + 1 })
+	const curr: number[] = Array.from({ length: b.length + 1 })
+	for (let j = 0; j <= b.length; j++) prev[j] = j
+	for (let i = 1; i <= a.length; i++) {
+		curr[0] = i
+		let rowMin = curr[0]!
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1
+			curr[j] = Math.min(prev[j]! + 1, curr[j - 1]! + 1, prev[j - 1]! + cost)
+			if (curr[j]! < rowMin) rowMin = curr[j]!
+		}
+		if (rowMin > cap) return cap + 1
+		for (let j = 0; j <= b.length; j++) prev[j] = curr[j]!
+	}
+	return prev[b.length]!
+}
+
+const suggestKey = (unknown: string, known: readonly string[]): string | null => {
+	let best: { key: string; dist: number } | null = null
+	for (const k of known) {
+		const d = editDistance(unknown, k, 2)
+		if (d <= 2 && (best === null || d < best.dist)) best = { key: k, dist: d }
+	}
+	return best?.key ?? null
+}
+
+const formatUnknownKeyWarning = (path: string, key: string, known: readonly string[]): string => {
+	const suggestion = suggestKey(key, known)
+	const hint = suggestion ? ` — did you mean "${suggestion}"?` : ""
+	return `house: ignoring unknown key "${key}" in ${path}${hint}`
+}
 
 /**
  * Reads a TOML file at `path`. Missing file → `undefined` for every key
- * (per-key fallthrough). Malformed TOML → `SourceError` (hard fail upstream).
+ * (per-key fallthrough). Malformed TOML → `SourceError` (hard fail
+ * upstream). Unknown top-level keys are warned about via `onWarning` and
+ * dropped — this preserves forward-compat with newer config schemas while
+ * still flagging typos like `them = "..."`.
  */
-const fileProvider = (path: string): ConfigProvider.ConfigProvider => {
+const fileProvider = (
+	path: string,
+	onWarning: (message: string) => void,
+): ConfigProvider.ConfigProvider => {
 	let cache: { data: Record<string, unknown> | null } | null = null
 	const load = Effect.gen(function* () {
 		if (cache !== null) return cache.data
@@ -69,17 +126,17 @@ const fileProvider = (path: string): ConfigProvider.ConfigProvider => {
 					cause,
 				}),
 		})
-		const unknown = Object.keys(parsed).filter((k) => !KNOWN_FILE_KEYS.has(k))
-		if (unknown.length > 0) {
-			const known = [...KNOWN_FILE_KEYS].join(", ")
-			return yield* Effect.fail(
-				new ConfigProvider.SourceError({
-					message: `unknown key${unknown.length > 1 ? "s" : ""} in ${path}: ${unknown.map((k) => `"${k}"`).join(", ")} (known: ${known})`,
-				}),
-			)
+		const known = [...KNOWN_FILE_KEYS]
+		const filtered: Record<string, unknown> = {}
+		for (const [k, v] of Object.entries(parsed)) {
+			if (KNOWN_FILE_KEYS.has(k)) {
+				filtered[k] = v
+			} else {
+				onWarning(formatUnknownKeyWarning(path, k, known))
+			}
 		}
-		cache = { data: parsed }
-		return parsed
+		cache = { data: filtered }
+		return filtered
 	})
 	return ConfigProvider.make((path) =>
 		Effect.gen(function* () {
@@ -112,8 +169,10 @@ const envProvider = (env: Record<string, string | undefined>): ConfigProvider.Co
 	const entries: Array<[string, string]> = []
 	const theme = env["HOUSE_THEME"]
 	const tone = env["HOUSE_TONE"]
+	const mdx = env["HOUSE_MDX"]
 	if (theme !== undefined) entries.push(["theme", theme])
 	if (tone !== undefined) entries.push(["tone", tone])
+	if (mdx !== undefined) entries.push(["mdx", mdx])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
 }
 
@@ -121,6 +180,7 @@ const cliProvider = (overrides: CliOverrides): ConfigProvider.ConfigProvider =>
 	const entries: Array<[string, string]> = []
 	if (overrides.theme !== null) entries.push(["theme", overrides.theme])
 	if (overrides.tone !== null) entries.push(["tone", overrides.tone])
+	if (overrides.mdx !== null) entries.push(["mdx", String(overrides.mdx)])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
 }
 
@@ -130,6 +190,8 @@ export interface LoadOptions {
 	readonly filePath?: string
 	/** Override env (tests). Defaults to `process.env`. */
 	readonly env?: Record<string, string>
+	/** Sink for non-fatal warnings (unknown keys). Defaults to stderr. */
+	readonly onWarning?: (message: string) => void
 }
 
 export const defaultConfigPath = (): string =>
@@ -156,11 +218,14 @@ export const formatConfigError = (err: unknown): string => {
 export const loadConfig = (
 	options: LoadOptions = {},
 ): Effect.Effect<HouseConfig, Config.ConfigError> => {
-	const cli = options.cli ?? { theme: null, tone: null }
+	const cli = options.cli ?? { theme: null, tone: null, mdx: null }
+	const onWarning = options.onWarning ?? ((msg) => process.stderr.write(`${msg}\n`))
 	const provider = cliProvider(cli).pipe(
 		ConfigProvider.orElse(envProvider(options.env ?? process.env)),
-		ConfigProvider.orElse(fileProvider(options.filePath ?? defaultConfigPath())),
+		ConfigProvider.orElse(fileProvider(options.filePath ?? defaultConfigPath(), onWarning)),
 		ConfigProvider.orElse(defaultsProvider()),
 	)
-	return schema.parse(provider)
+	return schema
+		.parse(provider)
+		.pipe(Effect.map((raw) => ({ theme: raw.theme, tone: raw.tone, mdx: raw.mdx === "true" })))
 }

package/src/discovery/walk.ts

@@ -19,6 +19,8 @@ export interface WalkOptions {
 	readonly all?: boolean
 	/** Group order within each directory. Default `dirs-first`. */
 	readonly sort?: SortOrder
+	/** Include `.mdx` files alongside `.md`/`.markdown`. Default `true`. */
+	readonly mdx?: boolean
 }
 
 export class DiscoveryError extends Data.TaggedError("DiscoveryError")<{
@@ -27,6 +29,7 @@ export class DiscoveryError extends Data.TaggedError("DiscoveryError")<{
 }> {}
 
 const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".mdx"])
+const MARKDOWN_EXTENSIONS_NO_MDX = new Set([".md", ".markdown"])
 const HARD_SKIP_DIRS = new Set(["node_modules", ".git", ".venv"])
 
 interface IgnoreLevel {
@@ -85,7 +88,7 @@ async function* walkDirGen(
 	dirPath: string,
 	rootPath: string,
 	parentLevels: readonly IgnoreLevel[],
-	opts: { all: boolean; sort: SortOrder },
+	opts: { all: boolean; sort: SortOrder; mdx: boolean },
 	signal: AbortSignal,
 ): AsyncGenerator<FileEntry, void, void> {
 	if (signal.aborted) return
@@ -119,7 +122,8 @@ async function* walkDirGen(
 
 		if (!entry.isFile()) continue
 		if (!opts.all && entry.name.startsWith(".")) continue
-		if (!MARKDOWN_EXTENSIONS.has(extname(entry.name).toLowerCase())) continue
+		const allowed = opts.mdx ? MARKDOWN_EXTENSIONS : MARKDOWN_EXTENSIONS_NO_MDX
+		if (!allowed.has(extname(entry.name).toLowerCase())) continue
 		if (!opts.all && isIgnored(entryPath, false, levels)) continue
 
 		yield {
@@ -137,7 +141,7 @@ async function* walkDirGen(
  * at its next `signal.aborted` check.
  *
  * Rules (see DESIGN.md §6):
- * - Extensions: `.md`, `.markdown`, `.mdx`.
+ * - Extensions: `.md`, `.markdown`, and `.mdx` (unless `mdx: false`).
  * - Hard skips (always): `node_modules`, `.git`, `.venv`.
  * - Hidden files/dirs (leading `.`) skipped unless `all: true`.
  * - `.gitignore` honored, including nested `.gitignore` files.
@@ -153,6 +157,7 @@ export const walk = (
 	const opts = {
 		all: options.all ?? false,
 		sort: options.sort ?? ("dirs-first" as SortOrder),
+		mdx: options.mdx ?? true,
 	}
 	const controller = new AbortController()
 	const iterable: AsyncIterable<FileEntry> = {

package/src/index.tsx

@@ -10,6 +10,7 @@
 
 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 { Cause, Duration, Effect, Fiber, Stream } from "effect"
@@ -19,17 +20,21 @@ import { Browser } from "./Browser.tsx"
 import { parseArgv, usage } from "./cli/argv.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, 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
@@ -56,11 +61,13 @@ 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, maxWidth, sidebarMode }: DiscoverShellProps) => {
+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)
@@ -69,7 +76,7 @@ const DiscoverShell = ({ target, all, sort, maxWidth, sidebarMode }: DiscoverShe
 	const countRef = useRef(0)
 
 	useEffect(() => {
-		const program = walk(target, { all, sort }).pipe(
+		const program = walk(target, { all, sort, mdx }).pipe(
 			Stream.groupedWithin(64, Duration.millis(60)),
 			Stream.runForEach((chunk) =>
 				Effect.sync(() => {
@@ -94,17 +101,17 @@ const DiscoverShell = ({ target, all, sort, maxWidth, sidebarMode }: DiscoverShe
 		return () => {
 			Effect.runFork(Fiber.interrupt(fiber))
 		}
-	}, [target, all, sort])
+	}, [target, all, sort, mdx])
 
 	const discoveryStatus = scanError ?? (scanning ? `indexing… ${countRef.current}` : null)
 
 	return (
 		<Browser
 			files={files}
-			title={target}
 			maxWidth={maxWidth}
 			discoveryStatus={discoveryStatus}
 			sidebarMode={sidebarMode}
+			updateNotice={updateNotice}
 		/>
 	)
 }
@@ -145,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,
@@ -183,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))
 
@@ -200,12 +210,20 @@ if (import.meta.main) {
 	}
 
 	const config = await Effect.runPromise(
-		loadConfig({ cli: { theme: args.theme, tone: args.tone } }),
+		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 } = config
+	const { theme: themeId, tone, mdx } = config
 	const themeDef = getThemeDefinition(themeId)
 	if (themeDef === undefined) {
 		// Unreachable: Config.schema validated themeId against themeDefinitions.
@@ -275,7 +293,17 @@ if (import.meta.main) {
 			}
 			sidebarMode = args.sidebar
 		}
-		await runTui({ target, themeId, tone, maxWidth, all: args.all, sort, sidebarMode })
+		await runTui({
+			target,
+			themeId,
+			tone,
+			maxWidth,
+			all: args.all,
+			sort,
+			mdx,
+			sidebarMode,
+			updateCheck: !args.noUpdateCheck,
+		})
 	}
 }
 
@@ -286,7 +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({
@@ -296,7 +328,9 @@ async function runTui({
 	maxWidth,
 	all,
 	sort,
+	mdx,
 	sidebarMode,
+	updateCheck,
 }: TuiBootOptions): Promise<void> {
 	let stats: Awaited<ReturnType<typeof stat>>
 	try {
@@ -306,6 +340,24 @@ 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 }
 
@@ -316,6 +368,7 @@ async function runTui({
 					target={target}
 					all={all}
 					sort={sort}
+					mdx={mdx}
 					maxWidth={maxWidth}
 					sidebarMode={sidebarMode}
 				/>

package/src/io/editor.ts

@@ -0,0 +1,162 @@
+/**
+ * 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) }
+	}
+}