IF Commons GitHub

System

0001Draft

0001-system · owner if · domain commons

Files, paths and errors

FR-001checkpassing

System MUST throw typed errors for what the host refuses (NotFound, AlreadyExists, PermissionDenied, IsADirectory, NotADirectory, DirectoryNotEmpty, AddrInUse, ConnectionRefused, BrokenPipe, TimedOut, NotSupported, InvalidData and the like), each a subclass of RuntimeError made from the host's error code, keeping the code, the path or address and the original error as its cause. A function whose failure is an expected outcome of what it is for (a download, a parse) MUST return a Result instead.

Enforced (check): .github: cd commons/system && bun test suite/ — fs.test.ts: each Node error code becomes its class with code, path and cause

Proved by: system/suite/fs.test.ts, system/suite/proc.test.ts

Written in: system/src/errors.ts

Tests: passed: suite/fs.test.ts a Node error code becomes its class, keeping the code, the path and the cause; anything el; passed: suite/fs.test.ts folders made, listed, stat'd and removed; removing what is not there is NotFound; passed: suite/fs.test.ts text and bytes written, appended and read; createNew and create:false refuse; passed: suite/proc.test.ts a program that does not exist is NotFound; an empty argument vector is refused

Cited by: errors, System

FR-002checkpassing

fs MUST give the file calls under short plain names and shapes (readTextFile, writeTextFile with append, create, createNew and mode, readFile, writeFile, remove with recursive, mkdir, stat, lstat, readDir, makeTempDir, makeTempFile, rename, copyFile, chmod, symlink, readLink, realPath, truncate, utime, and the synchronous forms in use), accept a path as a string or a file: URL, and give the helpers the harnesses wrote over them (exists, readTextOr, ensureDir, writeIfChanged in one step, listDirs, listFiles, walkFiles, sha256File, withTempDir).

Enforced (check): .github: cd commons/system && bun test suite/ — fs.test.ts: every call on a real temporary folder, the refusals

Proved by: system/suite/fs.test.ts

Written in: system/src/fs.ts

Tests: passed: suite/fs.test.ts folders made, listed, stat'd and removed; removing what is not there is NotFound; passed: suite/fs.test.ts text and bytes written, appended and read; createNew and create:false refuse; passed: suite/fs.test.ts Stolos's helpers: readTextOr, ensureDir, writeIfChanged, listDirs, listFiles, walkFiles, s; passed: suite/fs.test.ts regression: a temporary folder with no prefix is made inside the temporary folder, not bes; passed: suite/fs.test.ts temporary folders and files, rename, copy, chmod, links, realPath, truncate, utime

Cited by: fs, System

FR-003checkpassing

path MUST give the platform's path rules from node:path, both platforms' rules (posix, win32), file: URLs both ways and a path with / between its segments.

Enforced (check): .github: cd commons/system && bun test suite/ — proc.test.ts: both platforms' rules and file URLs

Proved by: system/suite/proc.test.ts

Written in: system/src/path.ts

Tests: passed: suite/proc.test.ts paths: the platform's rules, both platforms' rules, file URLs both ways

Cited by: System, path

FR-004checkpassing

fs.readDir MUST list a folder asynchronously (an async iterable of entries, usable with Array.fromAsync), and fs MUST give chown and symlinkSync.

Enforced (check): .github: cd commons/system && bun test suite/ — fs-more.test.ts: readDir async, chown, symlinkSync

Proved by: system/suite/fs-more.test.ts

Tests: passed: suite/fs-more.test.ts chown keeps or sets the owner and group, and symlinkSync makes a link (POSIX only, FR-018); passed: suite/fs-more.test.ts readDir is an async iterable of entries (as Array.fromAsync takes); a folder that is not t

FR-005checkpassing

fs.open (and openSync) MUST give a file handle (read, write, create, createNew, append, truncate, mode): reading and writing at its position, seek from the start, the position or the end, truncate, stat, sync, a web ReadableStream and WritableStream of its bytes, and close, also by using and await using. A handle MUST NOT give a file lock: one run at a time is lock (commons 0001-system FR-015) on every runtime, and a program that needs a lock uses it.

Enforced (check): .github: cd commons/system && bun test suite/ — fs-more.test.ts: file handles, seek, streams, using

Proved by: system/suite/fs-more.test.ts

Tests: passed: suite/fs-more.test.ts a file opened with append and written from two handles keeps both writes, each at the end; passed: suite/fs-more.test.ts a handle's bytes as a ReadableStream and into a WritableStream, each closing the file; usi; passed: suite/fs-more.test.ts an FsFile reads and writes at its position, seeks from the start, the position and the end; passed: suite/fs-more.test.ts open refuses: createNew where it exists, a missing file without create, no access asked fo

FR-006checkpassing

fs.copy MUST copy a file or a folder recursively (refusing to overwrite unless asked, keeping modes, copying a symbolic link as a link), and fs.walk MUST walk a folder as @std/fs's walk does (maxDepth, includeFiles, includeDirs, includeSymlinks, followSymlinks, exts, match, skip), in the byte order of the names at each level, so a walk is the same every time.

Enforced (check): .github: cd commons/system && bun test suite/ — fs-more.test.ts: copy and walk

Proved by: system/suite/fs-more.test.ts

Written in: system/library.ts, system/tools/check.ts, system/tools/pack.ts

Tests: passed: suite/fs-more.test.ts copy copies a file and a folder recursively, refuses a destination that exists unless over; passed: suite/fs-more.test.ts copy copies a symbolic link as a link (POSIX only, FR-018); passed: suite/fs-more.test.ts walk gives links as links, or follows them where asked, and does not loop on a link to its; passed: suite/fs-more.test.ts walk gives the same order every time, whatever order the names were made in; passed: suite/fs-more.test.ts walk goes depth first in the byte order of the names at each level, the root first, as @st

FR-007checkpassing

fs.symlink and fs.symlinkSync MUST take the type junction for a folder: on Windows a directory junction, which any account may make (a symbolic link needs administrator rights or Developer Mode there), its target made absolute as Windows requires; on Linux and macOS an ordinary symbolic link. A harness that links a folder for its own use (a scratch tree sharing node_modules) MUST use it, so it works for a person without administrator rights.

Enforced (check): .github: cd commons/system && bun test suite/ — fs.test.ts: a folder linked as a junction is read through it

Proved by: system/suite/fs.test.ts

Tests: passed: suite/fs.test.ts a folder linked as a junction is read through it, with no administrator rights on Windows

FR-008checkpassing

The module dirs MUST give, for a program's name, a system and an environment, its config, data, state, cache and runtime folders and its binary folder: on Linux and macOS $XDG_CONFIG_HOME, $XDG_DATA_HOME, $XDG_STATE_HOME, $XDG_CACHE_HOME and $XDG_RUNTIME_DIR with the program's name below each, else ~/.config, ~/.local/share, ~/.local/state, ~/.cache (and no runtime folder), and ~/.local/bin; and on Windows %APPDATA%\<name> for config and %LOCALAPPDATA%\<name>, %LOCALAPPDATA%\<name>\state and %LOCALAPPDATA%\<name>\cache for the others, with no binary folder. A value of an XDG_* variable MUST be honored on every system where it is set to an absolute path, Windows included, and MUST be ignored where it is not an absolute path. macOS MUST use the same folders as Linux, and MUST NOT use ~/Library, because git and gh, which this work stands on, do not. A folder MUST be undefined, and never guessed, where no home folder can be found and no variable names it.

Enforced (check): .github: cd commons/system && bun test suite/ — dirs.test.ts: the folders on Linux, macOS and Windows from the environment, the XDG variables honored, macOS as Linux, no home no folder

Proved by: system/suite/dirs.test.ts

Written in: system/src/dirs.ts

Tests: passed: suite/dirs.test.ts an XDG variable is honored where it is an absolute path, on Windows too (a path with / as ; passed: suite/dirs.test.ts macOS gives the folders Linux gives, and none is under ~/Library; passed: suite/dirs.test.ts on Linux the folders are the XDG defaults below the home with the program's name, there is; passed: suite/dirs.test.ts with no home and no variable every folder is undefined, never a guess, and a variable alon

Processes and programs

FR-009checkpassing

proc MUST give the environment (env.get, set, delete, has, toObject), the arguments, exit, the working folder, the platform (build.os, build.arch, build.target), the running runtime's name and version, which as command -v finds a program (with PATHEXT on Windows), and the running of a program by its argument vector and never through a shell: its input, environment and working folder given, its output kept as bytes or text or handed on line by line, a non-zero exit an outcome and not an error, a program that does not exist NotFound, and an abort signal stopping it with SIGTERM and then SIGKILL.

Enforced (check): .github: cd commons/system && bun test suite/ — proc.test.ts: the environment, the platform's names, which, a program with its input and output

Proved by: system/suite/network-interfaces.test.ts, system/suite/proc.test.ts

Written in: system/src/proc.ts

Tests: passed: suite/network-interfaces.test.ts networkInterfaces gives each address's name, family, address, netmask and internal, a loop; passed: suite/proc.test.ts a program that does not exist is NotFound; an empty argument vector is refused; passed: suite/proc.test.ts a program is stopped by its abort signal, with SIGTERM; passed: suite/proc.test.ts a program runs with its input, environment and working folder, and its status and output c; passed: suite/proc.test.ts each line comes as it is written, without its line ending, and the output is kept too and 4 more

Cited by: System, proc

FR-010checkpassing

proc.spawn MUST start a program by its argument vector and give a handle while it runs: its process id, its standard input as a web WritableStream and its output and errors as web ReadableStreams where they are piped, kill with a signal, status (a promise of its exit status and signal), output() (its whole output once it ends), ref and unref, and an abort signal and await using that stop it with SIGTERM and then SIGKILL; a program that does not exist MUST be NotFound, as for output (commons 0001-system FR-009).

Enforced (check): .github: cd commons/system && bun test suite/ — the library's tests of spawn: streams in and out, kill, status, NotFound

Proved by: system/suite/spawn.test.ts, telemetry/suite/process-span.test.ts

Tests: passed: suite/spawn.test.ts a program fed a megabyte through its stdin stream gives it back through its stdout stream,; passed: suite/spawn.test.ts a program that does not exist is NotFound at once; an empty argument vector is refused; passed: suite/spawn.test.ts a spawned gzip -dc fed a stream and read as one: the bytes out are the bytes in, unzipped; passed: suite/spawn.test.ts an abort signal stops it with SIGTERM; one that holds out is ended with SIGKILL after kill; passed: suite/spawn.test.ts await using stops a program that still runs when the block ends, and waits for it and 6 more

Cited by: Headless reach and targets

FR-011checkpassing

proc MUST give ppid, build.target (the target triple, such as x86_64-unknown-linux-gnu), unrefTimer (a timer that never keeps the process alive), and selfCommand(): the argument vector that runs the running program again with other arguments, on Bun and Node and from a binary that Bun compiled, so that a program that runs itself has one way to do it.

Enforced (check): .github: cd commons/system && bun test suite/ — the library's tests of spawn: ppid, build.target, unrefTimer, selfCommand

Proved by: system/suite/compile.test.ts, system/suite/spawn.test.ts

Tests: passed: suite/compile.test.ts a program built for this computer runs, its SHA-256 is given, its files are embedded, and ; passed: suite/spawn.test.ts an unreferenced timer never keeps the process alive, and fires while something else does; passed: suite/spawn.test.ts build.target is the target triple, and ppid is the parent's id; passed: suite/spawn.test.ts selfCommand on Bun and Node, and from a binary that Bun or Node compiled: the binary alone; passed: suite/spawn.test.ts selfCommand runs the running program again with other arguments, on this runtime

Cited by: System, proc

FR-012checkpassing

discover MUST find every program whose name begins with a given prefix on a search path, as Git finds git-<word>: each folder of the path in order, the first program of a name winning over a later one of the same name; a directory and a file that may not be run skipped and each kept with why it was skipped; on Windows, a name found by each extension PATHEXT lists (compared without regard to case, .EXE;.CMD;.BAT;.COM where it is not set), the extension left out of the name. The search path, the extensions and the platform MUST be able to be given rather than read from the process, so that Windows' rules are proven on any system, and the separator between the path's folders MUST come from that platform's rules (path.win32 or path.posix) and a folder and a name be joined by the running system's, never a hard-coded : or /.

Enforced (check): .github: cd commons/system && bun test suite/ — discover.test.ts: programs found by prefix, first wins, shadowed ones kept with why

Proved by: system/suite/discover.test.ts

Written in: system/src/discover.ts

Tests: passed: suite/discover.test.ts POSIX rules: first of a name wins; a directory and a file that may not be run are passed o; passed: suite/discover.test.ts Windows rules given as the platform: ';' between folders, PATHEXT in its order, the extens

Cited by: discover, System

FR-013checkpassing

compile MUST build a program into one binary with the pinned Bun (bun build --compile) for a target given (linux-x64, linux-arm64, darwin-x64, darwin-arm64, windows-x64) or for this computer, with the files it embeds, and give the binary's path and SHA-256; CI MUST build a small program for this computer on each system and run it.

Enforced (check): .github: cd commons/system && bun test suite/ — compile.test.ts: the arguments and a small program built and run

Proved by: system/suite/compile.test.ts

Written in: system/src/compile.ts

Tests: passed: suite/compile.test.ts a program built for this computer runs, its SHA-256 is given, its files are embedded, and ; passed: suite/compile.test.ts a missing Bun, a Bun that is not the pinned version, and a build that fails are each a Com; passed: suite/compile.test.ts compile asked for windows-x64 names an .exe; the other targets keep the name; targets of t; passed: suite/compile.test.ts the argument vector for each target: --target=bun-<target>, the outfile, extra options, th

Cited by: compile, System

FR-014checkpassing

git MUST read a repository by running git with an argument vector: the commit at HEAD, whether the tree is clean, the paths changed between two revisions, and a file as it is at a revision; each a Result, a repository that is not there an Err.

Enforced (check): .github: cd commons/system && bun test suite/ — git.test.ts: HEAD, cleanliness, changed paths and files at a revision in a temporary repository

Proved by: system/suite/git.test.ts

Written in: system/src/git.ts

Tests: passed: suite/git.test.ts a commit id is 40 or 64 lower-case hexadecimal digits; passed: suite/git.test.ts a folder that is not a repository, an unknown revision, an option-like revision and a miss; passed: suite/git.test.ts head, isClean, changedPaths and fileAt read a repository, with spaces and non-ASCII paths

Runs, watching and the terminal

FR-015checkpassing

System MUST give one run at a time by a lock file that appears only whole and only where none exists (the holder is written to a file of its own and given the name of the lock by a hard link, which is atomic and refused where the name is taken, so that no run reads a lock that is half written; where hard links are not given, the lock file is made where none exists and written after), holding its holder (process, command, since when, a token): a run that waits polls, says once whom it waits for and may give up after a time; a lock whose holder no longer runs is taken over, and so is one whose file cannot be read and has not changed for a grace (2 seconds by default), because a file just made by a run that has not finished writing it is a holder; an abandoned lock is removed by one run at a time under a guard (<lock>.takeover) after reading the lock again, so that a lock another run took in the meantime is never removed, and a guard left by a run that died is taken over after ten seconds; a child may inherit its parent's lock through an environment variable; and release removes the file only where it still holds the releasing holder's token, on exit too.

Enforced (check): .github: cd commons/ts && bun test tests/ — the lock's tests in commons' suite: one run at a time, the holder named, a stale lock

Proved by: system/suite/lock.test.ts

Written in: system/src/lock.ts

Tests: passed: suite/lock.test.ts a lock file that cannot be read yet, because its holder is still writing it, is held and n; passed: suite/lock.test.ts a lock is taken once, refused or waited for while held, and given back; passed: suite/lock.test.ts a lock whose holder no longer runs, or whose file is unreadable, is taken over; a child in; passed: suite/lock.test.ts an abandoned lock is removed by one run at a time: a fresh guard of a takeover makes the o; passed: suite/lock.test.ts contenders in one process take a lock one at a time, and every one of them gets it in turn and 1 more

Cited by: System, lock

FR-016checkpassing

watch MUST watch files and folders (recursively where asked) as an async iterable of events (create, modify, remove, rename, with the paths), joined over a given number of milliseconds so that one save is one event, on Linux, macOS and Windows, stopped by an abort signal or by using.

Enforced (check): .github: cd commons/system && bun test suite/ — watch.test.ts: events joined, recursive, stopped by abort

Proved by: system/suite/watch.test.ts

Written in: system/src/watch.ts

Tests: passed: suite/watch.test.ts a folder's files made, changed and removed are create, modify and remove events with their; passed: suite/watch.test.ts a recursive watch sees a file made in a new folder deep inside, and a file moved is one re; passed: suite/watch.test.ts a watch ends by its abort signal, by using, and by leaving the loop; a path that is not th; passed: suite/watch.test.ts a watch of a folder without recursive does not report what happens deeper; a watched file ; passed: suite/watch.test.ts an editor's save, a new file renamed over the old one, is one modify event after the join,

Cited by: System, watch

FR-017checkpassing

System MUST plan an operating system's own scheduled job from a generic description (a validated name, an owner's reverse-DNS domain and folder, an argument vector, a working folder, environment, an optional log, and a schedule of every N minutes, hourly, daily, weekly or monthly): a systemd user service and timer on Linux, a LaunchAgent on macOS and a Task Scheduler task running a .cmd file on Windows, with the commands that install and remove it; quote every argument for systemd and for cmd.exe so it reaches the program unchanged, and refuse, by a typed error naming the field, what cannot be (a line break, a quote in a cmd argument, a relative folder). System MUST install and remove a plan, writing its files and running its steps through a runner that tests replace, so no test touches a real scheduler.

Enforced (check): .github: cd commons/system && bun test suite/ — job-plan.test.ts and schedule.test.ts: exact units, plist and .cmd per OS, quoting round trips

Proved by: system/suite/job-plan.test.ts, system/suite/schedule.test.ts

Written in: system/src/job-plan.ts, system/src/schedule.ts

Tests: passed: suite/job-plan.test.ts arguments quoted for a .cmd file split back to the same argument vector, or are refused; passed: suite/job-plan.test.ts arguments quoted for systemd's ExecStart= split back to the same argument vector, or are r; passed: suite/job-plan.test.ts every schedule reads back the same from OnCalendar, the plist's StartCalendarInterval and ; passed: suite/job-plan.test.ts Linux: a systemd user service and timer, exactly; passed: suite/job-plan.test.ts Linux: a weekly job with a log, a variable with a space and arguments that need escapes and 13 more

Cited by: System, job-plan, schedule

FR-018checkpassing

tty MUST say whether a standard stream is a terminal and its size, turn raw mode on and off (NotSupported where standard input is not a terminal), and choose colour, emoji and width by a pure function of the environment and the terminal: colour only without NO_COLOR and only at a terminal unless FORCE_COLOR; TERM=dumb as no terminal; emoji where the locale is UTF-8, or on Windows in a terminal that says so, or on macOS with TERM_PROGRAM.

Enforced (check): .github: cd commons/ts && bun test tests/ — the console's tests of commons' suite: whether a stream is a terminal, raw mode, colour, emoji and width

Proved by: system/suite/tty.test.ts

Written in: system/src/tty.ts

Tests: passed: suite/tty.test.ts colour, emoji and width follow the environment and the terminal

Cited by: System, tty, palette, Headless command line

FR-019checkpassing

stdio MUST give standard input as a web ReadableStream, a read into a buffer, and the whole of it as bytes or text; and standard output and standard error as write (bytes or text), writeSync and a web WritableStream, for output read by programs (JSON, a protocol on standard input and output). It and console MUST be the only files of the runtime that write to standard output or standard error: what a person reads goes through the console, what a program reads through stdio.

Enforced (check): .github: cd commons/ts && bun test tests/ — the standard streams' tests of commons' suite: stdin, stdout and stderr as streams, bytes or text

Proved by: system/suite/stdio.test.ts

Written in: system/src/stdio.ts

Tests: passed: suite/stdio.test.ts JSON written by stdio while the console shows progress on standard error is whole, with no; passed: suite/stdio.test.ts a program reads its input whole or by read, and writes by write, writeSync and writable to; passed: suite/stdio.test.ts for any chunking of the input and any buffer size, read and then the rest whole give the i; passed: suite/stdio.test.ts read fills a buffer and keeps the rest for the next read; null at the end; the stream give

Cited by: System, stdio

The package

FR-020checkno test run

System MUST depend on Core, Formats and Crypto alone, MUST import no telemetry and no network (the telemetry of commons installs, by proc.setProcessTracer, the function that makes each program a process span, so that a program is run with nothing added where none is installed), MUST name no vendor's global, and MUST be published as compiled modules with their declarations as @intellectual-frontiers/system (commons 0032-libraries-by-concern FR-005), with an entry for the package and one for each module.

Enforced (check): .github: cd commons/system && bun run verify — the package is built, inspected and packed by tools/pack.ts; tests/commons-packages.test.ts installs the tarball and runs every entry on Node 26 and Bun and type-checks a consumer

Written in: system/about.ts, system/src/mod.ts

Acceptance scenarios

  1. Given a folder that is not there, When a file in it is read, Then NotFound is thrown with the path and the cause, per FR-001 and FR-002.
  2. Given a Windows path and a POSIX path, When they are joined with each platform's rules, Then each follows its own, per FR-003.
  3. Given a program that prints to both streams and exits 3, When it is run by its argument vector, Then the outcome holds both outputs and the code and nothing is thrown, per FR-009 and FR-010.
  4. Given two programs of one name on a search path, When programs are found by prefix, Then the first wins and the shadowed one is kept with why it was not taken, per FR-012.
  5. Given a lock file made by a run that is still going, When a second run asks for it, Then it says whom it waits for, per FR-015.
  6. Given the packed package installed under node_modules, When Node 26 and Bun import each entry, Then both give the same answer, per FR-020.

Out of scope

  • The network, the servers and the clients (the library net), the OpenTelemetry pipeline and the console that renders it (the library telemetry), and the test harness (the library test).

Edge cases

  • A program that cannot be found: NotFound with its name, never a shell's message, per FR-010.
  • A folder linked as a junction on Windows without administrator rights: read through it, per FR-007.
  • No home and no variable: the folders of a program are undefined, per FR-008.
  • No telemetry loaded: a program is run with nothing added to its environment, per FR-020.

Assumptions

  • Node 26 and Bun implement the node: builtins that this library names; a git is on the path where Git is read.

Open questions

  • None.

Key entities

  • Run outcome - the status, the code and the outputs of a program that ran, never an exception for a non-zero exit.
  • Lock - one run at a time, made of a lock file that holds its holder.
  • Process tracer - the function the telemetry installs so that a program is a span.

Success criteria

SC-001success criterion

A program written against this library behaves the same on Bun and Node 26 on the three systems.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

compile, discover, errors, fs, System, job-plan, lock, path, proc, schedule, stdio, tty, watch, palette, Headless command line, Headless reach and targets

Titles, headings, exports, tables, columns and requirements. Esc closes.