StoredFiletypeno test imports ittype StoredFile = { readonly name: string; readonly mtimeMs: number | undefined };A file of a folder: its name and when it was last changed (milliseconds), where the system keeps it.
What a program remembers between runs, in its folder of state (commons headless 0004-headless-cli FR-007, FR-008, FR-014): the run log of every run, pruned after thirty days, and when each hint was last shown. The folder is <XDG_STATE_HOME>/<program> as the system's dirsOf says (and the folders of Windows' known folders there); where no home folder can be found there is none, and a run keeps no log and shows every hint, never a guess. The files are reached through a port (StateStore), so that everything here is proved without a disk; the host binds it to the file system.
import { logName, stateDirOf } from "./state.ts";
stateDirOf("tool", (n) => ({ HOME: "/home/a" })[n], "linux"); // "/home/a/.local/state/tool"
logName(Date.UTC(2026, 10, 20, 10, 56, 11), 42); // "20261120T105611-42.log"StoredFiletypeno test imports ittype StoredFile = { readonly name: string; readonly mtimeMs: number | undefined };A file of a folder: its name and when it was last changed (milliseconds), where the system keeps it.
StateStoretypeno test imports ittype StateStore = {
readText(file: string): string | undefined;
/** Writes the file, making its folders. */
writeT… (428 characters)type StateStore = {
readText(file: string): string | undefined;
/** Writes the file, making its folders. */
writeText(file: string, text: string): void;
/** Adds to the end of the file, making it and its folders. */
appendText(file: string, text: string): void;
/** The files (not the folders) of a folder; none where it does not exist. */
list(dir: string): readonly StoredFile[];
remove(file: string): void;
};The files the program keeps, reached through a port: each operation is best effort and never throws (a hint shown twice is harmless; a lost log line is not a failure).
RUN_LOG_DAYSconstconst RUN_LOG_DAYS: 30How long a run log is kept.
stateDirOffunctionfunction stateDirOf(app: string, env: (name: string) => string | undefined, os: Os): string | undefinedThe folder a program keeps its state in, or undefined where no home folder can be found.
logDirOffunctionfunction logDirOf(stateDir: string, os: Os): stringThe folder of the run logs.
hintsFileOffunctionfunction hintsFileOf(stateDir: string, os: Os): stringThe file that remembers when each hint was shown.
logNamefunctionfunction logName(now: number, pid: number): stringThe name of a run's log: its time to the second, and the process: 20261120T105611-42.log.
pruneLogsfunctionfunction pruneLogs(store: StateStore, dir: string, os: Os, now: number, days?: number): readonly string[]Removes the run logs (*.log) of dir last changed more than days ago; gives the names removed.
lastLogfunctionfunction lastLog(store: StateStore, dir: string, os: Os): string | undefinedThe newest run log of a folder, or undefined.
readHintsfunctionfunction readHints(store: StateStore, file: string): Readonly<Record<string, number>>The hints' times, by id; empty where there is no file or it is not what it should be.
writeHintsfunctionfunction writeHints(store: StateStore, file: string, memory: Readonly<Record<string, number>>): voidRemembers the hints' times.
dueHintsfunctionfunction dueHints(store: StateStore | undefined, file: string | undefined, hints: readonly Hint[], now: number): readonly Hint[]The hints to show at the end of a run, by what the surface remembers (FR-008): every hint where there is no state (there is nothing to remember it by), else those not shown in the last seven days, with their time written once they are shown. Quiet runs and verbose runs do not come here.
RunLogclassclass RunLogA run's log: lines appended to one file, each with the time and a kind; it gives the number of the line it wrote, so that a problem can name its line.
| Member | Type | What it is |
|---|---|---|
path | string | |
write | (kind: string, text: string) => number | Writes a line; the number of the line, from 1. |