@carlesandres/house 0.3.1 → 0.4.1

package/src/commands/buildCommands.ts

@@ -0,0 +1,102 @@
+/**
+ * Derive palette commands from `browserBindings` plus the annotation map.
+ *
+ * The annotation map is the *only* hand-written list keyed by binding id:
+ * it carries (a) hide flags for bindings that are pure keystroke nav, and
+ * (b) title rewrites for bindings whose `description` reads as a help-row
+ * entry rather than a palette command. Every other binding is exposed
+ * verbatim — its `description` becomes the palette `title`, its first key
+ * becomes the `shortcut`.
+ *
+ * Commands close over the per-render `BrowserCtx`, same shape the keymap
+ * dispatcher uses, so the palette and the keymap fire the same action via
+ * different surfaces. See #70 design log §list construction (option 3b)
+ * for why this beat (a) a fully hand-written palette list and (b) deriving
+ * everything via #92's atom-driven registry.
+ */
+
+import { browserBindings, type BrowserCtx } from "../keymap/browser.ts"
+import { paletteOnlyCommands } from "./paletteOnlyCommands.ts"
+import type { AppCommand } from "./types.ts"
+
+interface Annotation {
+	/** Override the binding's `description` for palette display. */
+	readonly title?: string
+	/** Carried for #91's category headers; unused in v1's flat list. */
+	readonly category?: string
+	/** If true, the binding does not appear in the palette. */
+	readonly hidden?: boolean
+	readonly keywords?: readonly string[]
+}
+
+/**
+ * Pure-keystroke nav (j/k/space/b/[/]…) is intentionally hidden — those
+ * bindings have no command-shaped meaning. Reader prev/next file (`[`/`]`)
+ * and sidebar `open` (Return/l) are the borderline cases from #70 Q6a;
+ * hidden in v1, reconsider if users ask. Title rewrites convert
+ * help-overlay phrasing ("Toggle sidebar visibility") into imperative
+ * palette phrasing ("Toggle sidebar"). See #70 design log §6.
+ */
+const annotations: Record<string, Annotation> = {
+	// --- Keep, with title rewrites where the binding description reads awkwardly as a command ---
+	quit: { category: "App" },
+	"focus.toggle": { title: "Toggle focus", category: "View" },
+	"sidebar.toggle": { title: "Toggle sidebar", category: "View" },
+	"help.toggle": { title: "Show help", category: "App" },
+	"filter.open": { title: "Filter files…", category: "Navigation" },
+	"serve.current": { title: "Open in browser", category: "File" },
+	"theme.next": { category: "Appearance" },
+	"theme.prev": { category: "Appearance" },
+	"theme.toneToggle": { title: "Toggle dark/light tone", category: "Appearance" },
+
+	// --- Hide: pure keystroke navigation (j/k/space/b/g/G…) ---
+	"sidebar.down": { hidden: true },
+	"sidebar.up": { hidden: true },
+	"sidebar.jumpDown": { hidden: true },
+	"sidebar.jumpUp": { hidden: true },
+	"sidebar.pageDown": { hidden: true },
+	"sidebar.pageUp": { hidden: true },
+	"sidebar.top": { hidden: true },
+	"sidebar.bottom": { hidden: true },
+
+	// --- Hide: borderline reader nav. `[`/`]` and Return-to-open feel command-shaped
+	//     but are pure keystroke navigation under the hood. #70 Q6a — reconsider
+	//     if user feedback expects them in the palette.
+	"sidebar.open": { hidden: true },
+	"reader.back": { hidden: true },
+	"reader.prevFile": { hidden: true },
+	"reader.nextFile": { hidden: true },
+
+	// --- Hide: the palette opener itself shouldn't appear in the palette ---
+	"palette.open": { hidden: true },
+}
+
+/**
+ * Build the AppCommand list for a given render. Iterates `browserBindings`
+ * in array order (the empty-query palette renders in this order, by design
+ * — see #70 design log §empty-state ordering), drops hidden entries and
+ * those whose `when` predicate currently returns false, and resolves
+ * annotations to populate title / category / keywords.
+ */
+export const buildCommands = (ctx: BrowserCtx): readonly AppCommand[] => {
+	const out: AppCommand[] = []
+	for (const binding of browserBindings) {
+		const ann = annotations[binding.id]
+		if (ann?.hidden) continue
+		// Same gating the keymap dispatcher uses. Disabled bindings get
+		// hidden from the palette (per #70 Q5b — see #96 for the show-with-
+		// reason follow-up after the atom-driven migration).
+		if (binding.when && !binding.when(ctx)) continue
+		const cmd: AppCommand = {
+			id: binding.id,
+			title: ann?.title ?? binding.description,
+			...(ann?.category !== undefined && { category: ann.category }),
+			...(ann?.keywords !== undefined && { keywords: ann.keywords }),
+			...(binding.keys[0] !== undefined && { shortcut: binding.keys[0] }),
+			run: () => binding.run(ctx),
+		}
+		out.push(cmd)
+	}
+	for (const cmd of paletteOnlyCommands(ctx)) out.push(cmd)
+	return out
+}

package/src/commands/paletteOnlyCommands.ts

@@ -0,0 +1,16 @@
+/**
+ * Commands that exist *only* in the palette — no `browserBindings` entry.
+ *
+ * Empty in v1 by design (#70 Q6c). This file exists as scaffolding so
+ * future palette-only commands (#93 reveal-in-OS, #94 copy-path, …) have
+ * an obvious home that's already wired into `buildCommands.ts`.
+ *
+ * Commands here follow the same shape as keymap-derived ones: they take
+ * the per-render `BrowserCtx` so they can read selection state, mutate
+ * focus, surface notices, etc.
+ */
+
+import type { BrowserCtx } from "../keymap/browser.ts"
+import type { AppCommand } from "./types.ts"
+
+export const paletteOnlyCommands = (_ctx: BrowserCtx): readonly AppCommand[] => []

package/src/commands/score.ts

@@ -0,0 +1,78 @@
+/**
+ * Command palette scorer — ported from ghui's pre-May `commands.ts`.
+ *
+ * Tiered ranking: title-prefix → text-prefix → title-includes →
+ * text-includes → acronym → fuzzy-includes. Lower score wins. Ties broken
+ * by `browserBindings` array order (the `index` field) so the empty-query
+ * palette renders in the keymap's natural order. See #70 design log for
+ * why we didn't reach for `fuzzysort`.
+ */
+
+import type { AppCommand } from "./types.ts"
+
+const normalize = (text: string): string =>
+	text
+		.toLowerCase()
+		.replace(/[^a-z0-9#]+/g, " ")
+		.trim()
+
+const acronym = (text: string): string =>
+	normalize(text)
+		.split(" ")
+		.filter(Boolean)
+		.map((word) => word[0])
+		.join("")
+
+const fuzzyIncludes = (text: string, query: string): boolean => {
+	let index = 0
+	for (const char of text) {
+		if (char === query[index]) index++
+		if (index >= query.length) return true
+	}
+	return query.length === 0
+}
+
+const searchText = (command: AppCommand): string =>
+	normalize(
+		[command.title, command.category, command.shortcut, ...(command.keywords ?? [])]
+			.filter((s): s is string => Boolean(s))
+			.join(" "),
+	)
+
+/** Returns the tier (lower = better) or `null` if the query doesn't match. */
+const score = (command: AppCommand, query: string): number | null => {
+	const q = normalize(query)
+	if (q.length === 0) return 0
+	const title = normalize(command.title)
+	const text = searchText(command)
+	if (title.startsWith(q)) return 0
+	if (text.startsWith(q)) return 1
+	if (title.includes(q)) return 2
+	if (text.includes(q)) return 3
+	if (acronym(command.title).startsWith(q)) return 4
+	if (fuzzyIncludes(text, q.replaceAll(" ", ""))) return 5
+	return null
+}
+
+/**
+ * Filter and sort commands against a query. With an empty query, every
+ * command tiers to 0 and the original index breaks ties — so the result is
+ * the input list in its original order (which v1 uses as `browserBindings`
+ * order). See #70 design log §empty-state ordering.
+ */
+export const filterCommands = (
+	commands: readonly AppCommand[],
+	query: string,
+): readonly AppCommand[] =>
+	commands
+		.flatMap((command, index) => {
+			const tier = score(command, query)
+			return tier === null ? [] : [{ command, index, tier }]
+		})
+		.sort((a, b) => a.tier - b.tier || a.index - b.index)
+		.map(({ command }) => command)
+
+export const clampSelectedIndex = (index: number, commands: readonly AppCommand[]): number => {
+	if (commands.length === 0) return 0
+	return Math.max(0, Math.min(commands.length - 1, index))
+}

package/src/commands/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Palette command shape.
+ *
+ * Commands are derived at render time from `browserBindings` via the
+ * annotation map (`buildCommands.ts`). The `run` field closes over the
+ * per-render `BrowserCtx` so dispatching a command is equivalent to firing
+ * the corresponding key binding — single source of truth for the action,
+ * two surfaces (keymap + palette) that can invoke it.
+ *
+ * See issue #70 (and its design-log comments) for the rejected alternatives
+ * — atom-driven registry (#92), fully hand-written list, fuzzysort dep, etc.
+ */
+
+export interface AppCommand {
+	/** Stable id; matches the binding's id for keymap-derived commands. */
+	readonly id: string
+	/** Imperative-phrased label shown in the palette row. */
+	readonly title: string
+	/** Optional category for #91's grouped headers. Carried but unused in v1. */
+	readonly category?: string
+	/** Extra match terms (synonyms, alt phrasings). */
+	readonly keywords?: readonly string[]
+	/** Display-only shortcut hint (first key of the binding, if any). */
+	readonly shortcut?: string
+	readonly run: () => void
+}

package/src/config/load.ts

@@ -0,0 +1,231 @@
+/**
+ * Layered configuration loader.
+ *
+ * Precedence (high to low): CLI args → env vars → user TOML file → built-in defaults.
+ * Each source is wrapped as a `ConfigProvider` and composed via `orElse`,
+ * which falls through per-key when the upstream source returns `undefined`.
+ *
+ * The schema (`Config.schema` + `Schema.Literals`) validates `theme` against
+ * the registered theme ids and `tone` against `"dark" | "light"`. Validation
+ * failures and TOML parse errors both surface as `ConfigError` from `loadConfig`.
+ */
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { Config, ConfigProvider, Effect, Schema } from "effect"
+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 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", "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,
+		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). 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,
+	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
+		const file = Bun.file(path)
+		const exists = yield* Effect.promise(() => file.exists())
+		if (!exists) {
+			cache = { data: null }
+			return null
+		}
+		const text = yield* Effect.promise(() => file.text())
+		const parsed = yield* Effect.try({
+			try: () => Bun.TOML.parse(text) as Record<string, unknown>,
+			catch: (cause) =>
+				new ConfigProvider.SourceError({
+					message: `invalid TOML in ${path}: ${cause instanceof Error ? cause.message : String(cause)}`,
+					cause,
+				}),
+		})
+		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: filtered }
+		return filtered
+	})
+	return ConfigProvider.make((path) =>
+		Effect.gen(function* () {
+			const data = yield* load
+			if (data === null) return undefined
+			if (path.length === 0) {
+				return ConfigProvider.makeRecord(new Set(Object.keys(data)))
+			}
+			const head = path[0]
+			if (typeof head !== "string") return undefined
+			const value = data[head]
+			if (value === undefined) return undefined
+			if (typeof value === "string") return ConfigProvider.makeValue(value)
+			// Numbers/booleans coerced to their string form so Schema.Literals matches.
+			return ConfigProvider.makeValue(String(value))
+		}),
+	)
+}
+
+/**
+ * Reads `HOUSE_THEME` / `HOUSE_TONE` directly into a `fromUnknown` provider.
+ *
+ * We don't use `fromEnv().pipe(nested("HOUSE"), constantCase)` here because
+ * `ConfigProvider.orElse` composes providers via `.get(path)` (raw store
+ * access), which bypasses `mapInput`/`prefix`. That means an env provider
+ * built with `nested` + `constantCase` silently returns `undefined` once it
+ * sits behind an `orElse`. Reading env vars eagerly sidesteps the issue.
+ */
+const envProvider = (env: Record<string, string | undefined>): ConfigProvider.ConfigProvider => {
+	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))
+}
+
+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))
+}
+
+export interface LoadOptions {
+	readonly cli?: CliOverrides
+	/** Override the TOML path (tests). Defaults to `$XDG_CONFIG_HOME/house/config.toml`. */
+	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 =>
+	join(process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config"), "house", "config.toml")
+
+/**
+ * Renders a `ConfigError` (or any error) as a short single-line message
+ * suitable for `console.error("house: " + ...)`. Strips Effect's
+ * `ConfigError(SchemaError(...))` wrapping when present.
+ */
+export const formatConfigError = (err: unknown): string => {
+	if (err instanceof Config.ConfigError) {
+		const cause = err.cause
+		const raw = "message" in cause ? cause.message : String(cause)
+		return raw
+			.replace(/\s+at \[[^\]]+\]\s*$/, "")
+			.replace(/\s+/g, " ")
+			.trim()
+	}
+	if (err instanceof Error) return err.message
+	return String(err)
+}
+
+export const loadConfig = (
+	options: LoadOptions = {},
+): Effect.Effect<HouseConfig, Config.ConfigError> => {
+	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(), onWarning)),
+		ConfigProvider.orElse(defaultsProvider()),
+	)
+	return schema
+		.parse(provider)
+		.pipe(Effect.map((raw) => ({ theme: raw.theme, tone: raw.tone, mdx: raw.mdx === "true" })))
+}

package/src/discovery/walk.ts

@@ -1,6 +1,6 @@
 import { readdir, readFile } from "node:fs/promises"
 import { extname, join, relative, resolve } from "node:path"
-import { Data, Effect } from "effect"
+import { Data, Effect, Stream } from "effect"
 import ignore, { type Ignore } from "ignore"
 
 export interface FileEntry {
@@ -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 {
@@ -71,21 +74,38 @@ const sortEntries = <T extends { name: string; isDirectory: () => boolean }>(
 		return a.name.localeCompare(b.name)
 	})
 
-const walkDir = async (
+/**
+ * DFS generator. Yields each markdown FileEntry as it is discovered, before
+ * descending further. Per-directory sort still happens before yielding so
+ * arrival order within a directory matches the configured sort.
+ *
+ * Cancellation: `signal.aborted` is checked between syscalls. Node's
+ * `readdir` doesn't accept an AbortSignal, so a single in-flight `readdir`
+ * on a slow filesystem still runs to completion before we notice — the
+ * generator only exits at the next checkpoint.
+ */
+async function* walkDirGen(
 	dirPath: string,
 	rootPath: string,
 	parentLevels: readonly IgnoreLevel[],
-	results: FileEntry[],
-	opts: { all: boolean; sort: SortOrder },
-): Promise<void> => {
+	opts: { all: boolean; sort: SortOrder; mdx: boolean },
+	signal: AbortSignal,
+): AsyncGenerator<FileEntry, void, void> {
+	if (signal.aborted) return
+
 	let levels = parentLevels
 	if (!opts.all) {
 		const ig = await tryLoadGitignore(dirPath)
+		if (signal.aborted) return
 		if (ig) levels = [...parentLevels, { dir: dirPath, ig }]
 	}
 
 	const raw = await readdir(dirPath, { withFileTypes: true })
+	if (signal.aborted) return
+
 	for (const entry of sortEntries(raw, opts.sort)) {
+		if (signal.aborted) return
+
 		// 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
@@ -96,28 +116,32 @@ const walkDir = async (
 			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)
+			yield* walkDirGen(entryPath, rootPath, levels, opts, signal)
 			continue
 		}
 
 		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
 
-		results.push({
+		yield {
 			path: entryPath,
 			relativePath: relative(rootPath, entryPath),
 			name: entry.name,
-		})
+		}
 	}
 }
 
 /**
- * Walk a directory tree and return markdown files in a stable order.
+ * Stream markdown files under `root`. Entries arrive in DFS order respecting
+ * the per-directory sort. The stream is interruptible at syscall boundaries:
+ * the consumer's teardown trips an AbortController, and the generator exits
+ * 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.
@@ -128,16 +152,36 @@ const walkDir = async (
 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
+): Stream.Stream<FileEntry, DiscoveryError> => {
+	const absRoot = resolve(root)
+	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> = {
+		[Symbol.asyncIterator]() {
+			const gen = walkDirGen(absRoot, absRoot, [], opts, controller.signal)
+			return {
+				next: () => gen.next(),
+				return: async (value?: void) => {
+					controller.abort()
+					return gen.return(value as void)
+				},
+			}
 		},
-		catch: (cause) => new DiscoveryError({ root, cause }),
-	})
+	}
+	return Stream.fromAsyncIterable(iterable, (cause) => new DiscoveryError({ root, cause }))
+}
+
+/**
+ * Test/convenience helper: collect the full walk into an array. Mirrors the
+ * pre-streaming `walk()` signature so call sites that don't need streaming
+ * (notably tests) stay terse.
+ */
+export const walkToArray = (
+	root: string,
+	options: WalkOptions = {},
+): Effect.Effect<readonly FileEntry[], DiscoveryError> =>
+	Stream.runCollect(walk(root, options)).pipe(Effect.map((chunk) => Array.from(chunk)))