Module session 

Sessions: which app successive commands talk to, kept in a small file between invocations; the control-key discovery that lets connect and --app find a running app; and open, which launches one.

Layout under the state folder (Env::home):

sessions/<name>.json        {port, key_dir, pid?, exe?, log?, launched, trace?}
sessions/<name>/key/        the key folder handed to a launched app (0700)
sessions/<name>/app.log     a launched app's stdout and stderr
screenshots/                default place for `screenshot` without a path

Structs

Env

Where state lives and where apps keep their settings. Env::from_os for the real thing; tests point both somewhere private.

FoundKey

A control key file found on disk.

Session

What a session remembers.

Trace

A trace being recorded: a screenshot and a snapshot after every action.

Constants

KEY_DIR_ENV

The environment variable a launched app reads to know where to write its control key. A launcher (ashlar-debug open, a test harness) that starts an app with --control <port> sets this to the folder the app must write its key to, so it can read the key back without knowing the app’s settings folder.

Functions

check_name

A session name: [A-Za-z0-9_-]{1,64} (it becomes a file name).

find_keys

Key files under roots, newest first: only for port when given, only in folders whose path contains app (case-insensitive) when given.

free_port

A port nobody listens on right now (the OS picks it).

kill

Stop a process we started, when asking it to quit did not work.

launch

Start exe args… --control <port> with its key folder in the session folder and its output in the session log, and wait until it answers app.ping (or exits, or wait passes). An app that ignores ASHLAR_CONTROL_KEY_DIR is still found: its key is looked for in the settings folders.

list

Every recorded session name, sorted.

load

The session name, if one is recorded.

ping

Connect and check the app answers app.ping.

remove

Forget a session: its file, and the folder open made for it.

save

Record a session (written to a temporary file, then renamed, so a reader never sees half).

tail

The last n lines of a file (at most the last 64 KiB are read).

truthy

An environment flag’s value: anything but empty, 0, false, no or off turns it on.