IF Commons GitHub

surfaces/cli/state

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-headless-cli FR-007, 0004-headless-cli FR-008, 0004-headless-cli FR-014

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"

Source: commons/headless/src/surfaces/cli/state.ts

11 of 13 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

StoredFiletypeno test imports it
type 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 it
type 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_DAYSconst
const RUN_LOG_DAYS: 30

How long a run log is kept.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

stateDirOffunction
function stateDirOf(app: string, env: (name: string) => string | undefined, os: Os): string | undefined

The folder a program keeps its state in, or undefined where no home folder can be found.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

logDirOffunction
function logDirOf(stateDir: string, os: Os): string

The folder of the run logs.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

hintsFileOffunction
function hintsFileOf(stateDir: string, os: Os): string

The file that remembers when each hint was shown.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

logNamefunction
function logName(now: number, pid: number): string

The name of a run's log: its time to the second, and the process: 20261120T105611-42.log.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

pruneLogsfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

lastLogfunction
function lastLog(store: StateStore, dir: string, os: Os): string | undefined

The newest run log of a folder, or undefined.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

readHintsfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

writeHintsfunction
function writeHints(store: StateStore, file: string, memory: Readonly<Record<string, number>>): void

Remembers the hints' times.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

dueHintsfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

RunLogclass
class RunLog

A 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.

MemberTypeWhat it is
pathstring
write(kind: string, text: string) => numberWrites a line; the number of the line, from 1.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

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