jackherd 1.9.0 → 1.10.0

package/src/plans/waiting-click.ts

@@ -1,76 +1,231 @@
-import type { WaitingItem } from '../plan-format/waiting'
-import { fit, wrap } from '../terminal/text'
+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 { 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 screen column (1-based) `[ask]` starts in on the first line, five cells wide; null for a row without one. */
+  askColumn: number | null
+  /** 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[]
+}
+
+/** What a click does: expand or fold the row (its key), open an address, ask the coordinator to put the row, or nothing (null). */
+export type BlockClick = { toggle: string } | { open: string } | { ask: AskTarget }
+
+/**
+ * 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
+}
+
+/**
+ * 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 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]'
+const ASK_GAP = 1
 const FILE_MARK = '📎'
 const QUESTION_MARK = '?'
 const OPENABLE = /^(https?|file):\/\//
 
-/**
- * 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.
- */
-export type WaitingRow = { key: string; lines: string[]; cut: boolean; expanded: boolean; url: string | null }
-
-/** What a click does: expand or fold the row (its key), open an address, or nothing (null). */
-export type WaitingClick = { toggle: string } | { open: string }
-
 /** 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 roomOf = (width: number): number => Math.max(width - textWidth(`${WAITING_MARK} `), 1)
+/** 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 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 BAR_WIDTH = textWidth(`${WAITING_MARK} `)
+
+const roomOf = (width: number): number => Math.max(width - BAR_WIDTH, 1)
+
+/** The cells a row's text may take and the screen column `[ask]` starts in; no column for a row without a button. */
+const askLayout = (ask: AskTarget | null, width: number): { room: number; askColumn: number | null } => {
+  if (!ask) return { room: roomOf(width), askColumn: null }
+  const room = Math.max(roomOf(width) - (textWidth(ASK_BUTTON) + ASK_GAP), 1)
+  return { room, askColumn: BAR_WIDTH + room + ASK_GAP + 1 }
+}
+
+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}`)]
+}
+
+/**
+ * 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.
+ */
+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
+  })
+}
+
+const itemOf = (item: WaitingItem): BlockItem => ({
+  key: waitingKey(item),
+  mark: item.kind === WAITING_KIND.file ? FILE_MARK : QUESTION_MARK,
+  text: plain(item.item),
+  title: shortTitle(plain(item.item)),
+  url: item.kind === WAITING_KIND.file && item.url && OPENABLE.test(item.url) ? item.url : null,
+  ask: askOf(item),
+})
+
+const rowOf = (
+  { key, mark, lead, text, title = text, url, ask }: BlockItem,
+  expandedKeys: ReadonlySet<string>,
+  width: number,
+): BlockRow => {
+  const { room, askColumn } = askLayout(ask, 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 = ask ? [padVisible(first, room + ASK_GAP), ...rest] : [first, ...rest]
+  const dimFrom = dimStarts([first, ...rest], start, expanded && title !== text ? title.length : 0)
+  return { key, mark, lines, cut, expanded, url, ask, askColumn, preview: `${leadText}${title}`, dimFrom }
 }
 
-/** 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))
+
+/** 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)
+
+/** 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 WaitingRow[], firstLine: number, line: number): WaitingRow | 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 onAskButton = ({ askColumn }: BlockRow, column: number | undefined): boolean =>
+  askColumn !== null && column !== undefined && column >= askColumn && column < askColumn + textWidth(ASK_BUTTON)
+
+const clickOn = (row: BlockRow, onFirstLine: boolean, column: number | undefined): BlockClick | null => {
+  const { key, cut, expanded, url, ask } = row
+  if (ask && onFirstLine && onAskButton(row, column)) return { ask }
   if (url) return cut && !expanded ? { toggle: key } : { open: url }
   return cut ? { toggle: key } : null
 }
 
+/** 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'>,
+): boolean => pressed && button === MOUSE_BUTTON.left && row - 1 === headLine
+
 /**
- * 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 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 waitingClick = (
-  rows: readonly WaitingRow[],
+export const blockClick = (
+  rows: readonly BlockRow[],
   firstLine: number,
-  { button, row, pressed }: Pick<MouseEvent, 'button' | 'row' | 'pressed'>,
-): WaitingClick | null => {
+  {
+    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
+}

package/src/sync/kit-source.ts

@@ -9,10 +9,15 @@ import { parseKitPath } from './kit-path'
 
 export type KitLocation = { kitDirectory: string; version: string; packageRoot: string }
 
-/** What one kit module ships: its files and the text of its `hooks.json`, if any. */
-type KitModule = { name: string; files: KitFile[]; hooksText: string | undefined }
+/** What one kit module ships: its files and the texts of its `hooks.json` and `ask-rules.json`, if any. */
+type KitModule = { name: string; files: KitFile[]; hooksText: string | undefined; askRulesText: string | undefined }
 
 const MODULE_HOOKS_FILE = 'hooks.json'
+const MODULE_ASK_RULES_FILE = 'ask-rules.json'
+/** Files a module ships to sync itself, never into `.claude/`. */
+export const MODULE_DATA_FILES: readonly string[] = [MODULE_HOOKS_FILE, MODULE_ASK_RULES_FILE]
+
+const askRulesSchema = z.array(z.string().min(1))
 
 /** A test beside a kit script runs in this package and never ships into a project. */
 const TEST_FILE = /\.test\.ts$/
@@ -68,6 +73,21 @@ const mergeModuleHooks = (modules: KitModule[]): string | undefined => {
   return Object.keys(merged).length > 0 ? JSON.stringify(merged, null, 2) : undefined
 }
 
+/** The `permissions.ask` rules of every module's `ask-rules.json` (a JSON list of rules), each once, in module order. */
+const mergeModuleAskRules = (modules: KitModule[]): string[] => {
+  const rules = modules.flatMap(({ name, askRulesText }) => {
+    if (askRulesText === undefined) return []
+    const invalid = new Error(`Kit ${name}/${MODULE_ASK_RULES_FILE} is not a JSON list of permission rules`)
+    const parsed = askRulesSchema.safeParse(parseJsonOr(askRulesText, invalid))
+    if (!parsed.success) throw invalid
+    return parsed.data
+  })
+  return [...new Set(rules)]
+}
+
+const readOptional = async (moduleDirectory: string, relatives: string[], file: string): Promise<string | undefined> =>
+  relatives.includes(file) ? readFile(join(moduleDirectory, file), 'utf8') : undefined
+
 const listFiles = async (directory: string, prefix = ''): Promise<string[]> => {
   const entries = await readdir(join(directory, prefix), { withFileTypes: true })
   const nested = await Promise.all(
@@ -94,12 +114,11 @@ const readKitFile = async (moduleDirectory: string, relative: string): Promise<K
 const readModule = async (kitDirectory: string, name: string): Promise<KitModule> => {
   const moduleDirectory = join(kitDirectory, name)
   const relatives = (await listFiles(moduleDirectory)).sort()
-  const filePaths = relatives.filter((relative) => relative !== MODULE_HOOKS_FILE && !TEST_FILE.test(relative))
+  const filePaths = relatives.filter((relative) => !MODULE_DATA_FILES.includes(relative) && !TEST_FILE.test(relative))
   const files = await Promise.all(filePaths.map((relative) => readKitFile(moduleDirectory, relative)))
-  const hooksText = relatives.includes(MODULE_HOOKS_FILE)
-    ? await readFile(join(moduleDirectory, MODULE_HOOKS_FILE), 'utf8')
-    : undefined
-  return { name, files, hooksText }
+  const hooksText = await readOptional(moduleDirectory, relatives, MODULE_HOOKS_FILE)
+  const askRulesText = await readOptional(moduleDirectory, relatives, MODULE_ASK_RULES_FILE)
+  return { name, files, hooksText, askRulesText }
 }
 
 const listModuleNames = async (kitDirectory: string): Promise<string[]> => {
@@ -119,8 +138,8 @@ const listModuleNames = async (kitDirectory: string): Promise<string[]> => {
 /**
  * Reads the kit shipped with the package. Every directory under `kit/` is a module that mirrors
  * `.claude/` (`kit/workflow/skills/plan/SKILL.md` → `.claude/skills/plan/SKILL.md`); a module's
- * `hooks.json` holds its hooks by name, `{ "<name>": { event, matcher?, handler } }`, and is not
- * copied, nor is a `*.test.ts`. Files at the kit root, such as a README, belong to no module.
+ * `hooks.json` holds its hooks by name, `{ "<name>": { event, matcher?, handler } }`, and its
+ * `ask-rules.json` the `permissions.ask` rules a project install adds; neither is copied, nor is a `*.test.ts`. Files at the kit root, such as a README, belong to no module.
  *
  * A missing kit directory, or one without modules, is an error, never an empty kit: an empty kit
  * would make sync remove every untouched kit file from the project.
@@ -134,7 +153,7 @@ export const readKitSource = async ({
   const modules = await Promise.all(names.map((name) => readModule(kitDirectory, name)))
   assertUniquePaths(modules)
   const files = modules.flatMap((module) => module.files).sort((left, right) => (left.path < right.path ? -1 : 1))
-  return { version, files, hooksTemplate: mergeModuleHooks(modules) }
+  return { version, files, hooksTemplate: mergeModuleHooks(modules), askRules: mergeModuleAskRules(modules) }
 }
 
 const readPackageJson = async (path: string) => packageJsonSchema.parse(JSON.parse(await readFile(path, 'utf8')))

package/src/sync/kit.ts

@@ -6,4 +6,6 @@ export type KitSource = {
   files: KitFile[]
   /** The unrendered text of `kit/hooks.json`, if the kit ships hooks. */
   hooksTemplate: string | undefined
+  /** The `permissions.ask` rules of the kit's `ask-rules.json` files; none for a global install. */
+  askRules?: readonly string[]
 }

package/src/sync/manifest.ts

@@ -21,6 +21,8 @@ const manifestSchema = z.strictObject({
     z.string().regex(HOOK_NAME),
     z.strictObject({ base: hookDefinitionSchema, pending: sha256.optional() }),
   ),
+  /** The `permissions.ask` rules sync put into `settings.json`, which it removes once the kit drops them. */
+  askRules: z.array(z.string().min(1)).optional(),
   /** Checksum of the `settings.json.kit-new` sync wrote last. */
   settingsKitNew: sha256.optional(),
 })