Beagle SCM

JS-016: directory enumeration — io.readdir (dir-marked + callback-directed + recursive)

io exposes stat (kind incl. "dir") but no way to LIST a directory, so a JS utility cannot walk a tree, glob, or scan a worktree. The abc leaf already exists. Method: Issues.

Input

Context

• js/io.cpp has open/close/stat/read/write/mmap but no listing (verified: grep readdir/scandir in io.cpp → none).
• abc/FILE.h:242 FILEScanDir(path8bp, path8f, void0p) already wraps the syscall — a bindable leaf, no new abc work.
• Surfaced by the be status review: the worktree scan, any require- style resolver, and most CLI tools need a dir listing.

Goals

• io.readdir(path) → string[], one level, *dirs marked with a trailing /*; hidden (dot) entries skipped by default.
• 2nd arg is POLYMORPHIC: a FUNCTION is the directed callback ("more"/"enough"/"recur"); an OBJECT is options.
• Options {recursive, callback, hidden}: recursive:true auto-descends (flat array, or cb per entry); callback:fn = the directed cb; hidden:true includes dotfiles (default skip).

Constraints

• Marshal over FILEScanDir / FILEDeepScanDir (path8f = ok64(*)(void0p, path8p)); a C trampoline runs cb synchronously in-frame, never stashed (rule #4); a cb throw aborts + propagates.
• 2nd-arg dispatch: typeof === "function" → callback form; an object → options (with optional callback). recursive:true uses FILEDeepScanDir; a per-entry "recur" (non-recursive) nests FILEScanDir.
• hidden:false (default) skips basenames starting . (./.. already dropped by FILEScan). Dir-ness from the trailing / per entry. No ptr arith.

WIP

Design decisions

• (open) STATUS: 2nd iterate on reviewer feedback — unify the 2nd arg (nothing | callback fn | options object) before landing.
• (open) {recursive, callback, hidden} is the superset; bare-fn is sugar for {callback:fn}. Emitted paths stay root-relative (cb sees sub/child).

TODOs

• Stay current on trunk (JS-015 + JS-017 already in).
• Repro-first: fixture tree (files + a dotfile + subdir/child) — assert dir marking, enough early-stop, recur/recursive reach the child, and hidden default-skips the dotfile (present when hidden:true). Red→green.
• Implement the polymorphic 2nd arg + the three behaviors; update INDEX/API.

Blockers

• None.

Outcome

• LANDED 60194418 (2026-06-21): polymorphic io.readdir(path, arg) — absent → 1-level string[] (dirs marked /, dotfiles skipped); a function → directed cb (more/enough/recur); an object {recursive, callback, hidden} → superset (recursive→FILEDeepScanDir; hidden:false prunes dotfiles + hidden dirs via FILESKIP; recur no-op under recursive). 19 rows red→green; ctest -R JABC 18/18, ASAN/LSan clean; --force past the benign INDEX.md marker.