jackherd 1.9.0 → 1.11.0

package/src/plans/waiting-click.ts

@@ -1,76 +1,336 @@
-import type { WaitingItem } from '../plan-format/waiting'
-import { fit, wrap } from '../terminal/text'
+import type { ToneName } from '../config/tones'
+import { WAITING_KIND, type WaitingItem } from '../plan-format/waiting'
+import { fit, padVisible, wrap } from '../terminal/text'
 import { textWidth } from '../terminal/width'
+import { ASK_KIND, type AskTarget } from './ask-target'
 import { plain } from './layout-phase'
+import { DONE_KIND, type DoneTarget } from './row-targets'
 import { MOUSE_BUTTON, type MouseEvent } from './selection'
+import { shortTitle } from './task-name'
 
-/** How many for-you rows the herd draws; the rest is one `+<n>` line. */
-export const SHOWN_WAITING = 5
+/**
+ * One row of a block of the herd as drawn: its plain text lines (more than one while it is expanded; the first starts
+ * with `mark` and a blank and, for a row with `[ask]`, is padded to leave the button its cells), whether its text is wider than the pane (`cut`), whether it is expanded, and the address a
+ * click opens.
+ */
+export type BlockRow = {
+  key: string
+  mark: string
+  lines: string[]
+  cut: boolean
+  expanded: boolean
+  url: string | null
+  /** What the coordinator can be asked to put: a dialog question or a row of the board; null for files and appointments. */
+  ask: AskTarget | null
+  /** The buttons at the right edge of the first line, `[ask]` first, each with the screen column (1-based) it starts in. */
+  buttons: PlacedButton[]
+  /** What the folded block shows of the row: the time column, if any, and the short title, without the mark. */
+  preview: string
+  /** Per line, the index in it where the part behind the short title starts; the line's length where none of it is. */
+  dimFrom: number[]
+  /** The tone of the mark when it differs from the block's; absent for most rows. */
+  tone?: ToneName
+  /** The key in the expanded set that a click on the row flips, whatever its text or address; absent for most rows. */
+  toggle?: string
+  /** The row is dim from its text on; absent for most rows. */
+  dim?: boolean
+}
+
+/**
+ * What a click does: expand or fold the row (its key), open an address, ask the coordinator (to put the row to the
+ * user, to run an appointment now, to ask for a new time), close the row (`done`), or nothing (null).
+ */
+export type BlockClick = { toggle: string } | { open: string } | { ask: AskTarget } | { done: DoneTarget }
+
+/** A button of a row: its label as drawn and what a click on it does. */
+export type BlockButton = { label: string; click: BlockClick }
+
+/** A button with the screen column (1-based) its label starts in. */
+export type PlacedButton = BlockButton & { column: number }
+
+/**
+ * One row of a block of the herd before it is drawn: the key it expands by, the `mark` that starts it (kept apart so
+ * the block can paint it), its text, and what a click may do.
+ */
+export type BlockItem = {
+  key: string
+  mark: string
+  /** A column before the text, padded by the caller to the widest of the block (the time of an appointment). */
+  lead?: string
+  text: string
+  /** What the row shows while folded; the whole `text` when absent. */
+  title?: string
+  url: string | null
+  ask: AskTarget | null
+  /** The buttons after `[ask]`, in the order they are drawn. */
+  buttons?: readonly BlockButton[]
+  tone?: ToneName
+  /** The key in the expanded set that a click on the row flips, whatever its text or address. */
+  toggle?: string
+  /** The row is dim from its text on (an entry already asked about). */
+  dim?: boolean
+}
+
+/**
+ * What a click on a block is matched against, built from the block as it was drawn: `firstLine` is the screen line
+ * (0-based) of the first row, the line above it is the block's head; `rows` and `moreKey` are empty and null while the
+ * block is folded; `keys` are all its points, what a fold of the block remembers.
+ */
+export type BlockHit = {
+  firstLine: number
+  rows: readonly BlockRow[]
+  moreKey: string | null
+  keys: readonly string[]
+}
+
+/** How many rows a block of the herd (for-you, appointments) draws; the rest is one `+<n>` line. */
+export const SHOWN_BLOCK_ROWS = 5
+/** The key in the herd's expanded set that shows every point of the for-you block instead of the first five. */
+export const WAITING_MORE_KEY = 'more>waiting'
+/** The same for the appointment block. */
+export const APPOINTMENT_MORE_KEY = 'more>appointment'
+/** The same for the next block. */
+export const NEXT_MORE_KEY = 'more>next'
+/** The same for the sources block. */
+export const SOURCE_MORE_KEY = 'more>source'
 /** The bar and the blank that start every line of a for-you row. */
 export const WAITING_MARK = '▌'
 
+/** The button at the right edge of a question or a board row; a click on it, and only on it, asks the coordinator. */
+export const ASK_BUTTON = '[ask]'
+/** The button that closes a row: the board row gets its status, a sent file or a question its record. */
+export const DONE_BUTTON = '[done]'
+/** The appointment buttons that ask the coordinator to run the row now, and to ask the user for a new time. */
+export const RUN_BUTTON = '[run]'
+export const MOVE_BUTTON = '[move]'
+const ASK_GAP = 1
+const BUTTON_GAP = 1
 const FILE_MARK = '📎'
 const QUESTION_MARK = '?'
 const OPENABLE = /^(https?|file):\/\//
 
+/** The key of a row in the herd's expanded set: the record's id, else its text. */
+export const waitingKey = ({ id, item }: WaitingItem): string => `waiting>${id ?? item}`
+
+/** The keys of all open points, the shown ones and the `+<n>` rest alike: what the fold of the block remembers. */
+export const waitingKeys = (items: readonly WaitingItem[]): string[] => items.map(waitingKey)
+
+const BAR_WIDTH = textWidth(`${WAITING_MARK} `)
+
+const roomOf = (width: number): number => Math.max(width - BAR_WIDTH, 1)
+
+/** The buttons of an item, `[ask]` first when the item can be asked. */
+const buttonsOf = ({ ask, buttons = [] }: Pick<BlockItem, 'ask' | 'buttons'>): BlockButton[] => [
+  ...(ask ? [{ label: ASK_BUTTON, click: { ask } }] : []),
+  ...buttons,
+]
+
+const buttonsWidth = (buttons: readonly BlockButton[]): number =>
+  buttons.reduce((sum, { label }) => sum + textWidth(label), 0) + Math.max(buttons.length - 1, 0) * BUTTON_GAP
+
+/** The cells a row's text may take and the buttons with the screen columns they start in; none for a row without one. */
+const buttonLayout = (items: readonly BlockButton[], width: number): { room: number; placed: PlacedButton[] } => {
+  if (items.length === 0) return { room: roomOf(width), placed: [] }
+  const room = Math.max(roomOf(width) - (buttonsWidth(items) + ASK_GAP), 1)
+  let column = BAR_WIDTH + room + ASK_GAP + 1
+  const placed = items.map((button) => {
+    const at = column
+    column += textWidth(button.label) + BUTTON_GAP
+    return { ...button, column: at }
+  })
+  return { room, placed }
+}
+
+/** The labels of a row's buttons as drawn after its text, one blank apart, each painted with `paintLabel`. */
+export const buttonsText = (
+  buttons: readonly BlockButton[],
+  paintLabel: (label: string) => string = (label) => label,
+): string => buttons.map(({ label }) => paintLabel(label)).join(' ')
+
+const askOf = (item: WaitingItem): AskTarget | null => {
+  if (item.kind === WAITING_KIND.file) return null
+  if (item.kind === WAITING_KIND.question) return item.id ? { kind: ASK_KIND.question, id: item.id } : null
+  return { kind: ASK_KIND.boardRow, since: item.since, item: item.item }
+}
+
+/** The text wrapped to `room` cells behind `start` (the mark and the time column), the other lines indented to the column of the text. */
+const hangingLines = (start: string, text: string, room: number): string[] => {
+  const hang = textWidth(start)
+  const [first, ...rest] = wrap(text, Math.max(room - hang, 1))
+  return [`${start}${first}`, ...rest.map((line) => `${' '.repeat(hang)}${line}`)]
+}
+
 /**
- * One for-you row as drawn: its plain text lines (more than one while it is expanded), whether its text is wider than
- * the pane (`cut`), whether it is expanded, and the address a click opens.
+ * Per line, the index where the part behind the short title starts (the line's length while none of it is on the
+ * line): the title may take several lines, and the rest starts on the line where it ends. `titleLength` is 0 for a
+ * row without a short title.
  */
-export type WaitingRow = { key: string; lines: string[]; cut: boolean; expanded: boolean; url: string | null }
+const dimStarts = (lines: readonly string[], start: string, titleLength: number): number[] => {
+  let remaining = titleLength
+  return lines.map((line, index) => {
+    if (titleLength === 0) return line.length
+    const from = index === 0 ? start.length : textWidth(start)
+    const content = line.length - from
+    if (remaining > content) {
+      remaining -= content + 1
+      return line.length
+    }
+    const dimFrom = from + Math.max(remaining, 0)
+    remaining = 0
+    return dimFrom
+  })
+}
 
-/** What a click does: expand or fold the row (its key), open an address, or nothing (null). */
-export type WaitingClick = { toggle: string } | { open: string }
+/** What `[done]` closes: the record of a file or a question, else the row of the board; none for a record-less question. */
+const doneOf = (item: WaitingItem): DoneTarget | null => {
+  if (item.id) return { kind: DONE_KIND.record, id: item.id }
+  return item.kind === undefined ? { kind: DONE_KIND.boardRow, since: item.since, item: item.item } : null
+}
 
-/** The key of a row in the herd's expanded set: the record's id, else its text. */
-export const waitingKey = ({ id, item }: WaitingItem): string => `waiting>${id ?? item}`
+const doneButtons = (item: WaitingItem): BlockButton[] => {
+  const done = doneOf(item)
+  return done ? [{ label: DONE_BUTTON, click: { done } }] : []
+}
+
+const withPrefix = (prefix: string | undefined, text: string): string => (prefix ? `${prefix}: ${text}` : text)
 
-const roomOf = (width: number): number => Math.max(width - textWidth(`${WAITING_MARK} `), 1)
+const itemOf = (item: WaitingItem): BlockItem => ({
+  buttons: doneButtons(item),
+  key: waitingKey(item),
+  mark: item.kind === WAITING_KIND.file ? FILE_MARK : QUESTION_MARK,
+  text: withPrefix(item.prefix, plain(item.item)),
+  title: withPrefix(item.prefix, shortTitle(plain(item.item))),
+  url: item.kind === WAITING_KIND.file && item.url && OPENABLE.test(item.url) ? item.url : null,
+  ask: askOf(item),
+})
 
-const rowOf = (item: WaitingItem, expandedKeys: ReadonlySet<string>, width: number): WaitingRow => {
-  const text = `${item.kind === 'file' ? FILE_MARK : QUESTION_MARK} ${plain(item.item)}`
-  const room = roomOf(width)
-  const cut = textWidth(text) > room
-  const key = waitingKey(item)
+const rowOf = (item: BlockItem, expandedKeys: ReadonlySet<string>, width: number): BlockRow => {
+  const { key, mark, lead, text, title = text, url, ask, tone, toggle, dim } = item
+  const { room, placed } = buttonLayout(buttonsOf(item), width)
+  const leadText = lead === undefined ? '' : `${lead} `
+  const start = `${mark} ${leadText}`
+  const cut = title !== text || textWidth(`${start}${text}`) > room
   const expanded = cut && expandedKeys.has(key)
-  const url = item.kind === 'file' && item.url && OPENABLE.test(item.url) ? item.url : null
-  return { key, lines: expanded ? wrap(text, room) : [fit(text, room)], cut, expanded, url }
+  const [first, ...rest] = expanded ? hangingLines(start, text, room) : [fit(`${start}${title}`, room)]
+  const lines = placed.length > 0 ? [padVisible(first, room + ASK_GAP), ...rest] : [first, ...rest]
+  const lineParts = [first, ...rest]
+  const dimFrom = dim
+    ? lineParts.map((_, index) => (index === 0 ? mark.length + 1 : 0))
+    : dimStarts(lineParts, start, expanded && title !== text ? title.length : 0)
+  const preview = `${leadText}${title}`
+  return {
+    key,
+    mark,
+    lines,
+    cut,
+    expanded,
+    url,
+    ask,
+    buttons: placed,
+    preview,
+    dimFrom,
+    ...(tone && { tone }),
+    ...(toggle && { toggle }),
+    ...(dim && { dim }),
+  }
 }
 
-/** The rows the herd draws for what waits on the user: the first five, each folded to one line unless expanded. */
+/**
+ * The rows a block of the herd draws: the first five, or all of them while `moreKey` is in the expanded set; each
+ * folded to one line unless expanded.
+ */
+export const blockRows = (
+  items: readonly BlockItem[],
+  expandedKeys: ReadonlySet<string>,
+  width: number,
+  moreKey: string,
+): BlockRow[] =>
+  (expandedKeys.has(moreKey) ? items : items.slice(0, SHOWN_BLOCK_ROWS)).map((item) => rowOf(item, expandedKeys, width))
+
+/** Every item as a row, for a block that limits its rows itself (the sources block, five entries per source). */
+export const allBlockRows = (
+  items: readonly BlockItem[],
+  expandedKeys: ReadonlySet<string>,
+  width: number,
+): BlockRow[] => items.map((item) => rowOf(item, expandedKeys, width))
+
+/** The rows the herd draws for what waits on the user. */
 export const waitingRows = (
   items: readonly WaitingItem[],
   expandedKeys: ReadonlySet<string>,
   width: number,
-): WaitingRow[] => items.slice(0, SHOWN_WAITING).map((item) => rowOf(item, expandedKeys, width))
+): BlockRow[] => blockRows(items.map(itemOf), expandedKeys, width, WAITING_MORE_KEY)
 
-const rowAt = (rows: readonly WaitingRow[], firstLine: number, line: number): WaitingRow | null => {
+/** The key of the `+<n>` line of a block with `count` points, null while the block has no more than it shows. */
+export const moreKeyOf = (count: number, key: string): string | null => (count > SHOWN_BLOCK_ROWS ? key : null)
+
+const rowAt = (
+  rows: readonly BlockRow[],
+  firstLine: number,
+  line: number,
+): { row: BlockRow; onFirstLine: boolean } | null => {
   let first = firstLine
   for (const row of rows) {
-    if (line < first + row.lines.length) return line >= first ? row : null
+    if (line < first + row.lines.length) return line >= first ? { row, onFirstLine: line === first } : null
     first += row.lines.length
   }
   return null
 }
 
-const clickOn = ({ key, cut, expanded, url }: WaitingRow): WaitingClick | null => {
+const buttonAt = ({ buttons }: BlockRow, column: number | undefined): PlacedButton | undefined =>
+  column === undefined
+    ? undefined
+    : buttons.find((button) => column >= button.column && column < button.column + textWidth(button.label))
+
+const clickOn = (row: BlockRow, onFirstLine: boolean, column: number | undefined): BlockClick | null => {
+  const { key, cut, expanded, url, toggle } = row
+  const button = onFirstLine ? buttonAt(row, column) : undefined
+  if (button) return button.click
+  if (toggle) return { toggle }
   if (url) return cut && !expanded ? { toggle: key } : { open: url }
   return cut ? { toggle: key } : null
 }
 
 /**
- * What a plain left click on the for-you block does. A row that is cut off expands on the first click; then a
- * question folds on the next click and a file or Artifact opens. A row that fits opens its file on the first click, a
- * question does nothing. The `+<n>` line, other lines, a click with a modifier (ctrl is left to the terminal's own link
- * opening), a release and the wheel do nothing. `firstLine` is the screen line (0-based) of the first row, as
- * `renderScreen` returns it.
+ * What Enter does on a row: the question is asked where the row has an `[ask]` button, else the row opens its address,
+ * expands when cut off, or does nothing. Never a `[done]` or `[run]`: those close or start something, so only a click on
+ * the button does that.
  */
-export const waitingClick = (
-  rows: readonly WaitingRow[],
-  firstLine: number,
+export const mainClickOf = (row: BlockRow): BlockClick | null => {
+  const ask = row.buttons.find((button) => button.label === ASK_BUTTON)
+  return ask ? ask.click : clickOn(row, true, undefined)
+}
+
+/** Whether a plain left click hit the head line of a block, which folds and opens it. `headLine` is 0-based. */
+export const blockHeadClick = (
+  headLine: number,
   { button, row, pressed }: Pick<MouseEvent, 'button' | 'row' | 'pressed'>,
-): WaitingClick | null => {
+): boolean => pressed && button === MOUSE_BUTTON.left && row - 1 === headLine
+
+/**
+ * What a plain left click on a block does. A click on the `[ask]` button of a question or a board row (the columns of
+ * its first line) asks the coordinator, whatever the fold. Any other click on a row that is cut off expands or folds it,
+ * except that a file or Artifact opens on the click after it expanded; a row that fits opens its file or does nothing.
+ * The `+<n>` line, the line right
+ * under the rows, toggles `moreKey` (all points or the first five); `moreKey` is null while the block has no such
+ * line. Other lines, a click with a modifier (ctrl is left to the terminal's own link opening), a release and the
+ * wheel do nothing. `firstLine` is the screen line (0-based) of the first row, as `renderScreen` returns it.
+ */
+export const blockClick = (
+  rows: readonly BlockRow[],
+  firstLine: number,
+  {
+    button,
+    row,
+    pressed,
+    column,
+  }: Pick<MouseEvent, 'button' | 'row' | 'pressed'> & Partial<Pick<MouseEvent, 'column'>>,
+  moreKey: string | null = null,
+): BlockClick | null => {
   if (!pressed || button !== MOUSE_BUTTON.left) return null
-  const target = rowAt(rows, firstLine, row - 1)
-  return target ? clickOn(target) : null
+  const line = row - 1
+  const moreLine = firstLine + rows.reduce((sum, { lines }) => sum + lines.length, 0)
+  if (moreKey !== null && line === moreLine) return { toggle: moreKey }
+  const target = rowAt(rows, firstLine, line)
+  return target ? clickOn(target.row, target.onFirstLine, column) : null
 }

package/src/plans/waiting-records.ts

@@ -0,0 +1,39 @@
+import { openWaitingItems, type WaitingItem } from '../plan-format/waiting'
+import type { PlanLanguage } from '../vocabulary'
+import { type QuestionRecord, questionWaitingItems } from './question-records'
+import { readQuestionRecords } from './questions-read'
+import { type SentFileRecord, sentWaitingItems } from './sent-files'
+import { readSentRecords } from './sent-files-read'
+
+/** The two logs that wait on the user, as read from the main checkout. */
+export type WaitingRecords = { sent: SentFileRecord[]; questions: QuestionRecord[] }
+
+/** The files sent to the user and the questions left unanswered that no one closed, files first. */
+export const waitingItemsOfRecords = (
+  sent: readonly SentFileRecord[],
+  questions: readonly QuestionRecord[],
+  now: number,
+): WaitingItem[] => [...sentWaitingItems(sent, now), ...questionWaitingItems(questions, now)]
+
+/** What waits on the user: the board's own rows (none when `board` is null), then the sends and questions. */
+export const waitingItemsOf = (
+  board: string | null,
+  language: PlanLanguage,
+  { sent, questions }: WaitingRecords,
+  now: number,
+): WaitingItem[] => [
+  ...(board === null ? [] : openWaitingItems(board, language)),
+  ...waitingItemsOfRecords(sent, questions, now),
+]
+
+/** Both logs read from `root`; each file is read once, whoever uses it. */
+export const readWaitingRecords = (root: string): WaitingRecords => ({
+  sent: readSentRecords(root),
+  questions: readQuestionRecords(root),
+})
+
+/** The files sent to the user and the questions left unanswered that no one closed, files first, read from `root`. */
+export const recordWaitingItems = (root: string, now: number): WaitingItem[] => {
+  const { sent, questions } = readWaitingRecords(root)
+  return waitingItemsOfRecords(sent, questions, now)
+}

package/src/plans/waiting-window.ts

@@ -0,0 +1,8 @@
+import { DAY_MS } from '../plan-format/clock'
+
+/** A question or a sent file waits on the user this long at most; a later answer or `jh waiting close` ends it earlier. */
+const WAITING_DAYS = 3
+
+/** Whether a record that was closed at `closedAt` (null: never) and began at `at` still waits on the user at `now`. */
+export const isStillWaiting = (closedAt: number | null, at: number, now: number): boolean =>
+  closedAt === null && now - at <= WAITING_DAYS * DAY_MS

package/src/preview/command.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
+import { ensurePrivateDirectory, writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import { pageDirectoryOf, systemLocation } from '../shared/private-location'
 import { openInBrowser } from '../terminal/open'
 import { runGh } from '../watch/gh'
 import { embedExternalImages, fetchImage } from './embed'
@@ -48,6 +49,28 @@ export const inlineImage = (root: string, path: string): string | null => {
   return `data:${type};base64,${readFileSync(file).toString('base64')}`
 }
 
+/**
+ * Writes the page to `out` when the user named one, else to `preview-<name>.html` in the user's private page directory
+ * (verified by `ensurePrivateDirectory`, written through `writePrivateFile`), never to a fixed name in the shared
+ * temporary directory; returns the path written.
+ */
+export const writePreviewPage = (
+  file: string,
+  page: string,
+  out: string | null,
+  pageDirectory: string = pageDirectoryOf(systemLocation()),
+): string => {
+  if (out !== null) {
+    const chosen = resolve(out)
+    writeFileSync(chosen, page)
+    return chosen
+  }
+  ensurePrivateDirectory(pageDirectory)
+  const path = join(pageDirectory, `preview-${basename(file, '.md')}.html`)
+  writePrivateFile(path, page)
+  return path
+}
+
 /**
  * `jh preview <markdown-file> [--out <path>] [--open]`: renders the file through GitHub's markdown API and writes a
  * page that shows it in GitHub and in npm style, light and dark, and at phone width. The package's own images come
@@ -70,8 +93,7 @@ export const run = async (args: string[]): Promise<number> => {
     const { html: rewritten, failed } = await embedExternalImages(local, fetchImage)
     if (failed > 0)
       console.error(`${failed} external ${failed === 1 ? 'image' : 'images'} could not be embedded and stay linked`)
-    const out = resolve(options.out ?? join(tmpdir(), `jh-preview-${basename(file, '.md')}.html`))
-    writeFileSync(out, previewPage({ title: basename(file), html: rewritten }))
+    const out = writePreviewPage(file, previewPage({ title: basename(file), html: rewritten }), options.out)
     console.log(out)
     const reason = options.open ? openInBrowser(out) : null
     if (reason) console.error(`could not open the page: ${reason}`)

package/src/shared/private-location.ts

@@ -0,0 +1,89 @@
+import { lstatSync, readFileSync, type Stats } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { ensurePrivateDirectory, isOwnedBy } from '../../kit/hooks/hooks/shared/private-directory'
+
+type Entry = Pick<Stats, 'uid' | 'mode' | 'isDirectory' | 'isSymbolicLink'>
+
+/** What choosing a private location reads from the system; the default is the real one (`systemLocation`). */
+export type LocationSystem = {
+  env: Record<string, string | undefined>
+  temporaryDirectory: string
+  uid: number | undefined
+  /** What sits at the path, without following a link; null for nothing. */
+  entryAt: (path: string) => Entry | null
+}
+
+const PAGE_DIRECTORY_PREFIX = 'jackherd'
+const GROUP_OR_OTHER = 0o077
+
+const isPrivateDirectoryEntry = (entry: Entry | null, uid: number | undefined): boolean =>
+  entry !== null &&
+  !entry.isSymbolicLink() &&
+  entry.isDirectory() &&
+  isOwnedBy(entry, uid) &&
+  (entry.mode & GROUP_OR_OTHER) === 0
+
+/**
+ * Where files only the user may read are kept: `$XDG_RUNTIME_DIR` when it is an absolute path to a directory of the
+ * user, no link, that neither group nor others may enter; else the temporary directory, which may be the shared `/tmp`
+ * and so needs a private level of its own below it (`userDirectoryOf`, `ensurePrivateLevels`).
+ */
+export const runtimeBaseOf = ({ env, temporaryDirectory, uid, entryAt }: LocationSystem): string => {
+  const runtime = env.XDG_RUNTIME_DIR
+  return runtime && isAbsolute(runtime) && isPrivateDirectoryEntry(entryAt(runtime), uid) ? runtime : temporaryDirectory
+}
+
+/** The user's own level below `base`: `<base>/<prefix>-<uid>`, with `user` where the platform has no user ids. */
+export const userDirectoryOf = (base: string, prefix: string, uid: number | undefined): string =>
+  join(base, `${prefix}-${uid ?? 'user'}`)
+
+/**
+ * The user's directory for pages a browser opens: below the temporary directory, never the runtime directory, which a
+ * sandboxed browser may not reach.
+ */
+export const pageDirectoryOf = (system: LocationSystem): string =>
+  userDirectoryOf(system.temporaryDirectory, PAGE_DIRECTORY_PREFIX, system.uid)
+
+const entryAt = (path: string): Entry | null => {
+  try {
+    return lstatSync(path)
+  } catch {
+    return null
+  }
+}
+
+export const systemLocation = (): LocationSystem => ({
+  env: process.env,
+  temporaryDirectory: tmpdir(),
+  uid: process.getuid?.(),
+  entryAt,
+})
+
+/**
+ * Whether `userDirectory` and `directory` (itself or a directory right below it) both exist as directories of the user,
+ * no link, closed to group and others; creates nothing, for readers that must not read from a level someone else
+ * planted.
+ */
+export const isPrivateLevels = (userDirectory: string, directory: string, system: LocationSystem): boolean =>
+  [userDirectory, directory].every((level) => isPrivateDirectoryEntry(system.entryAt(level), system.uid))
+
+/** The text of a regular file; null for nothing, a link or anything else (a FIFO would block the read). */
+export const readPrivateText = (path: string): string | null => {
+  try {
+    return lstatSync(path).isFile() ? readFileSync(path, 'utf8') : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Creates `directory`, the user level `userDirectory` itself or a directory right below it, and verifies each level
+ * with `ensurePrivateDirectory`, the user level first: nothing is created inside a level someone else owns or planted
+ * as a link, and this throws before anything is written there.
+ */
+export const ensurePrivateLevels = (userDirectory: string, directory: string): string => {
+  ensurePrivateDirectory(userDirectory)
+  if (directory !== userDirectory) ensurePrivateDirectory(directory)
+  return directory
+}

package/src/shared/stat-cache.ts

@@ -0,0 +1,48 @@
+import { statSync } from 'node:fs'
+
+/** What tells a file changed without reading it: when it was last written and how large it is. */
+export type FileStamp = { mtimeMs: number; size: number }
+
+type Entry<T> = FileStamp & { value: T }
+
+/** What was read from each file, by path, with the stamp it was read at. */
+export type StatCache<T> = Map<string, Entry<T>>
+
+/** A cache and the keys one round of reads asked for; `dropUnused` clears the rest at the end of the round. */
+export type CacheRound<V> = { entries: Map<string, V>; used: Set<string> }
+
+/** A round over a `StatCache`. */
+export type StatRound<T> = CacheRound<Entry<T>>
+
+const isUnchanged = (entry: FileStamp, stamp: FileStamp): boolean =>
+  entry.mtimeMs === stamp.mtimeMs && entry.size === stamp.size
+
+/** Removes what no read of the round used, so a file that is gone does not stay in the cache. */
+export const dropUnused = (cache: Map<string, unknown>, used: ReadonlySet<string>): void => {
+  for (const key of [...cache.keys()]) if (!used.has(key)) cache.delete(key)
+}
+
+const stampOf = (path: string): FileStamp | null => {
+  try {
+    const { mtimeMs, size } = statSync(path)
+    return { mtimeMs, size }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * What `read` makes of the file, asked again only when its modification time or size changed since the cache saw it.
+ * A file that cannot be stat-ed is read every time and not kept. The `key` (the path unless the result also depends
+ * on something else, such as how much of the file is read) is noted in `used`, for `dropUnused`.
+ */
+export const readCached = <T>(round: StatRound<T>, path: string, read: (path: string) => T, key: string = path): T => {
+  round.used.add(key)
+  const stamp = stampOf(path)
+  if (!stamp) return read(path)
+  const kept = round.entries.get(key)
+  if (kept && isUnchanged(kept, stamp)) return kept.value
+  const value = read(path)
+  round.entries.set(key, { ...stamp, value })
+  return value
+}