Beagle SCM

JS-016 LOW: 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.