@gavin-hu/my-pi-agent 0.15.0 → 0.16.0

package/extensions/file-browse/styles.ts

@@ -0,0 +1,124 @@
+/**
+ * The browse pages' stylesheet: the shared Bytefly shell and components, then
+ * the page-only `browse-*` rules layered on top.
+ *
+ * Kept apart from `html.ts` so the renderers stay a renderer and the CSS stays
+ * findable as one block; the `bf-*` kit itself lives in `lib/web`.
+ */
+
+import {
+	SIDEBAR_COLLAPSE_MAX,
+	WEB_BASE_CSS,
+	WEB_COMPONENTS_CSS,
+	WEB_LAYOUT_CSS,
+	WEB_THEME_CSS,
+} from "../../lib/web/index.ts";
+
+/** The shared shell, components, and the page-only `browse-*` rules. */
+export const BROWSE_CSS = `${WEB_BASE_CSS}
+${WEB_THEME_CSS}
+${WEB_LAYOUT_CSS}
+${WEB_COMPONENTS_CSS}
+${WEB_THEME_CSS}
+${WEB_LAYOUT_CSS}
+${WEB_COMPONENTS_CSS}
+.browse-side{padding:var(--space-3)}
+.browse-root{flex:1 1 auto;direction:rtl;text-align:left}
+.browse-git{font-family:var(--font-mono)}
+.browse-quick-open{display:flex;align-items:center;justify-content:space-between;gap:var(--space-2);width:100%;margin-bottom:var(--space-2);padding:6px var(--space-2);border:1px solid var(--border);border-radius:var(--radius-md);background:var(--canvas);color:var(--muted);font:var(--fs-sm) var(--font-ui);cursor:pointer}
+.browse-quick-open:hover{border-color:var(--accent);color:var(--accent)}
+.browse-quick-open kbd{font-family:var(--font-mono);font-size:var(--fs-xs);color:var(--dim)}
+.browse-side__filters{display:flex;align-items:center;gap:var(--space-2);margin-bottom:var(--space-2)}
+.browse-side__filters .bf-field{flex:1 1 auto;min-width:0}
+.browse-side__filters .bf-btn{flex:0 0 auto;white-space:nowrap}
+.browse-cat{width:16px;height:16px;flex:0 0 16px;color:var(--accent)}
+.browse-cat.doc{color:var(--muted)}.browse-cat.img{color:var(--success)}.browse-cat.cfg{color:var(--warn)}.browse-cat.arc{color:var(--warn)}
+.browse-heading{margin:0 0 var(--space-3);font-size:var(--fs-lg)}
+.browse-listing th.bf-table__size,.browse-listing th.bf-table__when{text-align:right}
+.browse-listing th.bf-table__size{width:96px}
+.browse-listing th.bf-table__when{width:140px}
+.browse-dotfile .bf-table__name a{opacity:.72}
+.browse-broken{color:var(--muted);text-decoration:line-through}
+.browse-link-mark{color:var(--muted);font-size:var(--fs-xs)}
+.browse-when{display:none}
+body.palette-open{overflow:hidden}
+.browse-diff{font-family:var(--font-mono);gap:5px}
+.browse-diff:hover{color:var(--accent);text-decoration:none}
+.browse-diff__dot{color:var(--warn);font-size:9px;line-height:1}
+.browse-change{color:var(--warn);font-size:9px;line-height:1;flex:0 0 auto}
+/* Live status: the connection chip keeps its own border and padding so a tone
+   swap only changes the colour, and the footer line reads as one muted clause. */
+.browse-live{font-family:var(--font-mono);border:1px solid currentColor;border-radius:var(--radius-pill);padding:2px 10px}
+.browse-live__glyph{font-size:9px;line-height:1}
+.browse-live-line{color:var(--muted);font-variant-numeric:tabular-nums}
+.browse-live-line::after{content:" · "}
+.browse-diff-totals{font-family:var(--font-mono)}
+.browse-diff-add{color:var(--success)}
+.browse-diff-del{color:var(--danger)}
+.browse-diff-scope{color:var(--muted);font-size:var(--fs-sm);font-weight:var(--fw-medium)}
+.browse-diff-toolbar{display:flex;align-items:center;gap:var(--space-3);margin:0 0 var(--space-3);flex-wrap:wrap}
+.browse-diff-stat{margin:0 0 var(--space-3);font:var(--fs-xs)/1.5 var(--font-mono);color:var(--muted);white-space:pre-wrap;overflow-x:auto}
+.browse-diff th.browse-diff-status{width:72px}
+.browse-diff th.browse-diff-word{width:130px}
+.browse-diff-badge{display:inline-block;min-width:16px;text-align:center;font:var(--fw-semibold) var(--fs-xs) var(--font-mono);border-radius:var(--radius-sm);padding:1px 5px;border:1px solid var(--border)}
+.browse-diff-badge--M{color:var(--warn);border-color:currentColor}
+.browse-diff-badge--A,.browse-diff-badge--Q{color:var(--success);border-color:currentColor}
+.browse-diff-badge--D{color:var(--danger);border-color:currentColor}
+.browse-diff-badge--R,.browse-diff-badge--C{color:var(--accent);border-color:currentColor}
+.browse-diff-orig{color:var(--muted);font-size:var(--fs-xs)}
+.browse-diff-word{color:var(--muted);font-size:var(--fs-sm)}
+.browse-diff-no{display:inline-block;width:46px;padding-right:var(--space-2);text-align:right;color:var(--dim);user-select:none}
+.browse-diff-sign{display:inline-block;width:16px;text-align:center;color:var(--muted);user-select:none}
+.bf-diff-line--add{background:var(--success-soft)}
+.bf-diff-line--add .browse-diff-sign{color:var(--success)}
+.bf-diff-line--del{background:var(--danger-soft)}
+.bf-diff-line--del .browse-diff-sign{color:var(--danger)}
+.bf-diff-line--hunk{color:var(--accent);background:var(--canvas)}
+.bf-diff-line--meta{color:var(--muted)}
+.bf-diff-line--note{color:var(--muted);font-style:italic}
+/* A hunk header pins to the top of the diff viewport while its body scrolls.
+   Each hunk is a section so the pinned header is bounded by its own body and
+   cannot stack on the next one. */
+.bf-diff-hunk{display:block}
+.bf-diff .bf-diff-line--hunk{position:sticky;top:0;z-index:1}
+/* Reading progress, pinned to the sticky header's bottom edge. */
+.browse-progress{position:absolute;left:0;right:0;bottom:-1px;height:2px;overflow:hidden}
+.browse-progress__fill{display:block;height:100%;width:0;background:var(--accent);transition:width var(--motion-fast) linear}
+/* File and diff pages: a measured reading column inside the card. */
+/* The Markdown body fills the card, so the scroll box is the card's width: its
+   scrollbar sits at the card edge. The measure lives on the blocks themselves:
+   on .bf-md it would be a flex item with auto inline margins, which is
+   shrink-to-fit, so a short document collapsed to its widest line. */
+.browse-measure{--browse-measure:1012px}
+.browse-measure .bf-md{--browse-gutter:max(0px,calc((100% - var(--browse-measure)) / 2));max-width:none;margin-inline:0;padding-inline:var(--space-5);padding-block:var(--space-4) var(--space-6)}
+.browse-measure .bf-md>*{max-width:var(--browse-measure);margin-inline:auto}
+/* Tables start at the prose column and take only the gutter to its right, so a
+   wide window widens them without a dead band on their left. Code stays inside
+   the measure with the rest of the prose. */
+.browse-measure .bf-md>.md-table-frame{max-width:none;padding-left:var(--browse-gutter)}
+/* A table wider than the pane scrolls, but an overlay scrollbar is invisible
+   until it moves; a gradient on the frame marks the columns still out of view.
+   It has to be the frame: the scroller clips its own content, so a pseudo-element
+   inside it would scroll away with the table. */
+.browse-measure .bf-md>.md-table-frame.browse-table-more::after{content:"";position:absolute;top:0;right:0;bottom:0;width:40px;pointer-events:none;background:linear-gradient(to left,var(--surface) 12%,transparent)}
+.bf-card__meta{font-variant-numeric:tabular-nums}
+.browse-diff-summary{font-family:var(--font-mono);white-space:nowrap}
+.browse-diff-summary .browse-diff-add{color:var(--success)}
+.browse-diff-summary .browse-diff-del{color:var(--danger)}
+.browse-hunks{color:var(--muted)}
+/* Wide screens: pin quick open and the filter, and scroll the tree on its own
+   box. The sidebar is a details element, whose content sits in an anonymous
+   wrapper with no definite height, so the panel fills the sidebar by absolute
+   positioning; below the sidebar breakpoint the disclosure keeps normal page
+   scroll. */
+@media not (max-width:${SIDEBAR_COLLAPSE_MAX}px){
+.browse-sidebar{position:relative;overflow:hidden}
+.browse-side{position:absolute;inset:0;display:flex;flex-direction:column;overflow:hidden}
+.browse-side .bf-tree{flex:1 1 auto;min-height:0;overflow:auto}
+}
+@media (max-width:820px){
+.browse-root{order:9;flex:1 1 100%;direction:ltr;text-align:left}
+}
+@media (max-width:520px){
+.bf-toolbar .bf-theme-toggle{margin-left:auto}
+}`;

package/extensions/file-open/README.md

@@ -152,5 +152,4 @@ of the model's active tool set unless a script explicitly reaches for it.
 | `index.ts` | The extension factory: registers `open_path` and the `/open` command, resolves the target, and routes a launch failure to `ctx.ui.notify`. |
 | `open.ts` | `normalizeTarget` and `buildCommand` (pure), `resolveTarget` (existence check), and `openTarget` with the injectable launcher, which reports a start failure and a meaningful non-zero exit. |
 | `schema.ts` | `TOOL_NAME`, the TypeBox `parameters` / `outputSchema`, and the `OpenPathArgs` / `OpenPathResult` types. |
-| `open.test.ts` | Pure-module tests for normalization, resolution, per-platform commands, and the launcher seam. |
-| `extension.test.ts` | Extension-surface tests: registration, disabling, the tool call, and the command. |
+| `extension.test.ts` | The capability suite: normalization, resolution, per-platform commands, the launcher seam, registration, disabling, the tool call, and the command. |

package/extensions/{document → file-read}/README.md

@@ -1,6 +1,6 @@
-# document — read local PDF, DOCX, DOC, ODT, RTF, and XLSX files as text
+# file-read — read local PDF, DOCX, DOC, ODT, RTF, and XLSX files as text
 
-`document` adds a `read_doc` tool that extracts plain text from a local `.pdf`,
+`file-read` adds a `read_doc` tool that extracts plain text from a local `.pdf`,
 `.docx`, `.doc`, `.odt`, `.rtf`, or `.xlsx` file, paged with `startIndex` /
 `maxChars`. Extraction runs in process through JavaScript libraries (`unpdf`,
 `mammoth`, `word-extractor`, `fflate` + `fast-xml-parser`, `rtf-parser`,
@@ -8,34 +8,30 @@
 the effective working directory with the same symlink-aware guard the built-in
 path tools use.
 
-## Tool rendering
-
-How the `read_doc` call and its result look in the transcript — the call line as a headline and the body indented under it:
-
-<img src="../../assets/tools/read_doc.png" alt="The read_doc tool's result: the call line and an indented body with the file path, format, size, and the extracted text preview" width="100%">
-
 ## Quickstart
 
 ```bash
-pi --extension ./extensions/document   # this extension only
+pi --extension ./extensions/file-read   # this extension only
 pi -e .                                # the package from this checkout
 pi install ./                          # install the package for a user
 ```
 
 The extraction libraries are ordinary dependencies, so a normal install brings
-them along. Then ask the model to read a document, or call the tool directly:
+them along. Then ask the model to read a document or a workbook, or call the
+tool directly:
 
 ```jsonc
 { "path": "docs/spec.pdf" }
 { "path": "docs/spec.pdf", "startIndex": 40000, "maxChars": 40000 }
+{ "path": "report.xlsx" }
 ```
 
 ## What it does
 
 - Extracts plain text from `.pdf`, `.docx`, `.doc`, `.odt`, `.rtf`, and `.xlsx`
   files for the model to read.
-- Pages long documents: when output is truncated, call again with the
-  `startIndex` named in the note.
+- Pages long files: when output is truncated, call again with the `startIndex`
+  named in the note.
 - Slices by code point, so CJK and emoji stay well-formed.
 - Reads only inside the effective working directory, resolving symlinks so a
   link cannot escape it.
@@ -47,6 +43,11 @@ them along. Then ask the model to read a document, or call the tool directly:
 `read_doc` — direct exposure, active by default, read-only, closed-world
 (no network).
 
+How the call and its result look in the transcript — the call line as a headline
+and the body indented under it:
+
+<img src="../../assets/tools/read_doc.png" alt="The read_doc tool's result: the call line and an indented body with the file path, format, size, and the extracted text preview" width="100%">
+
 | Parameter | Type | Meaning |
 |---|---|---|
 | `path` | string, required, 1–4096 chars | Path to a `.pdf`, `.docx`, `.doc`, `.odt`, `.rtf`, or `.xlsx`, relative to the working directory (or absolute inside it). |
@@ -67,7 +68,9 @@ Result (`details` / `structuredContent`):
 | `text` | The clean slice, without the header or truncation note. |
 
 The model-facing `content` is a header (`Path:`, `Format:`, `Size:`), a blank
-line, the slice, and a truncation note when applicable.
+line, the slice, and a truncation note when applicable. A workbook reads as one
+`[Sheet]` heading per worksheet followed by tab-separated rows, so the shape of
+the text says what the file was.
 
 Errors are thrown for: a missing or non-file path, a path outside the root, an
 unsupported extension (with a targeted hint for legacy `.xls`), a disabled
@@ -116,7 +119,7 @@ sanitized error path.
 
 ## Configuration
 
-The `document` section of the shared `bytefly.json`, loaded from
+The `file-read` section of the shared `bytefly.json`, loaded from
 `~/.pi/agent/bytefly.json` then `<cwd>/.pi/bytefly.json` (project wins), each
 merged over the defaults and clamped:
 
@@ -128,12 +131,13 @@ merged over the defaults and clamped:
 | `formats` | `{ "pdf": true, "docx": true, "doc": true, "odt": true, "rtf": true, "xlsx": true }` | — | Per-format on/off, merged over each registry entry's default; unknown keys are ignored. |
 
 ```jsonc
-// bytefly.json → "document"
+// bytefly.json → "file-read"
 { "maxChars": 80000, "extractTimeoutMs": 60000, "formats": { "docx": false } }
 ```
 
-`doc.json` is not read, and neither is the old per-extension `document.json`;
-run `bun run config:migrate` to move a `document.json` into the shared file.
+The section was named `document` before this extension was renamed; the loader
+reads only `file-read`, and `bun run config:migrate` renames an existing
+`document` section and moves a legacy `document.json` into it.
 
 ## Security
 
@@ -145,14 +149,14 @@ run `bun run config:migrate` to move a `document.json` into the shared file.
   parser receives.
 - **Size-capped and time-bounded.** Files larger than `maxFileBytes` are rejected
   before any parser runs, and a parser that outlasts `extractTimeoutMs` is
-  abandoned so the turn is not held open by one document.
+  abandoned so the turn is not held open by one file.
 - **No subprocesses.** Extraction never spawns a process, so it grants no
   privileges beyond the current process.
-- **Untrusted text.** Extracted document text is treated as untrusted: it is
-  returned as model-facing `content` and data. The collapsed transcript draws
-  only a sanitized summary; the expanded transcript draws a sanitized,
-  line-capped preview (`PREVIEW_LINES`). Control characters are stripped before
-  a theme colour is applied, so raw document bytes never reach the terminal.
+- **Untrusted text.** Extracted text is treated as untrusted: it is returned as
+  model-facing `content` and data. The collapsed transcript draws only a
+  sanitized summary; the expanded transcript draws a sanitized, line-capped
+  preview (`PREVIEW_LINES`). Control characters are stripped before a theme
+  colour is applied, so raw file bytes never reach the terminal.
 - **Worktree guard.** Under the `worktree` extension, `read_doc` is in the
   worktree guard's path-tool map, so `blockReadEscapes` / `blockSymlinkEscapes`
   apply to it exactly as to the built-in `read`.
@@ -171,11 +175,11 @@ Each extractor builds a plain-text document from the format's bytes:
 | XLSX | `exceljs` | One `[Sheet]` heading per non-empty worksheet, then tab-separated rows. Dates and numbers use the workbook's displayed text; formulas show their computed value. Cell formatting is dropped. |
 
 The tool is pageable across the whole extracted text, so a word-processing
-document or workbook is read in the same `startIndex` / `maxChars` way as a PDF.
+document or a workbook is read in the same `startIndex` / `maxChars` way as a PDF.
 
 Each call is bounded by `extractTimeoutMs` (30 s by default). A parser that
 outlasts the deadline is abandoned — the read fails with the limit named, and a
-late result is discarded — so a pathological document cannot park the turn.
+late result is discarded — so a pathological file cannot park the turn.
 
 ## Supported formats
 
@@ -194,13 +198,13 @@ The format table in `formats.ts` is the single source of truth; the handler,
 config defaults, and error listing all derive from it.
 
 1. Add the extraction library to `dependencies` in `package.json`.
-2. Add `extensions/document/extract/<fmt>.ts` exporting a `DocExtractor` that
-   `await import(...)`s its library, reads the bytes with `readDocBytes`, and
+2. Add `extensions/file-read/extract/<fmt>.ts` exporting a `FormatExtractor` that
+   `await import(...)`s its library, reads the bytes with `readFormatBytes`, and
    normalizes the output. Keep the parsing in a pure, exported helper so it is
    testable without a real file.
-3. Add a `DocumentFormat` entry to `FORMATS` and widen the `id` union.
-4. Add `extract/<fmt>.test.ts` with a real minimal fixture, and extend
-   `formats.test.ts` / `config.test.ts`.
+3. Add a `ReadFormat` entry to `FORMATS` and widen the `id` union.
+4. Add the new extractor to `extract/extract.test.ts` with a real minimal
+   fixture, and extend `tool.test.ts` for format selection and config.
 5. Add a row to the tables above.
 
 `tool.ts`, `paging.ts`, and the config normalizer need no changes.
@@ -235,51 +239,63 @@ config defaults, and error listing all derive from it.
 
 | Aspect | Contract |
 |---|---|
-| Registration | `document(pi)` in `index.ts` calls `registerDocTool(pi)`, which registers `read_doc`. The factory only registers; no parser loads until a read needs it. |
+| Registration | `fileRead(pi)` in `index.ts` calls `registerReadTool(pi)`, which registers `read_doc`. The factory only registers; no parser loads until a read needs it. |
 | Tool | `read_doc`, direct exposure and active on registration (the defaults), default (`parallel`) execution, `annotations: { readOnlyHint: true, openWorldHint: false }`, TypeBox `parameters` and `outputSchema`, and `renderCall`/`renderResult` (reuse `context.lastComponent`; read `context.cwd` and `context.isError`). |
 | State | None persisted. Per-result state lives in the tool-result `details` / `structuredContent`; the renderer reads only that. |
 | Lifecycle | No `session_start` / `session_shutdown` hooks: each read imports a parser, runs it, and holds no long-lived resources. |
 | Host seams | `resolveEffectiveCwd` (`lib/env.ts`), `isInsideReal` / `realPathOfNearest` (`lib/path.ts`), `loadConfigSection` (`lib/config.ts`), `stripControlChars` / `sanitize` / `formatTokens` (`lib/format.ts`), `SEPARATORS` (`lib/tui/glyphs.ts`). |
-| Config | The `document` section of the shared `bytefly.json` via `loadConfigSection` (`~/.pi/agent`, `<cwd>/.pi`). |
+| Config | The `file-read` section of the shared `bytefly.json` via `loadConfigSection` (`~/.pi/agent`, `<cwd>/.pi`). |
 
 ## Design notes
 
-A separate tool rather than an overload of the built-in `read`: the worktree
+**A separate tool rather than an overload of the built-in `read`.** The worktree
 extension owns the built-in path tools and re-registers them, so overloading
-`read` would fight that machinery. A table-driven registry keeps future formats
-additive, and extracting in process means the tool works on any host without a
-per-format install step and without spawning a child process per read.
+`read` would fight that machinery. The tool also stays one tool for all six
+formats, the way Pi's `read` covers text and images: the split would be a choice
+the model can get wrong (and an extra entry in the worktree guard's path map) in
+exchange for prompt copy, while the workbook-specific guidance fits in one
+`promptGuidelines` bullet. A second tool becomes worth it only when it carries
+behaviour a document read must not have, such as reading named worksheets.
+
+**The name.** `document` stopped describing the job once XLSX joined the table:
+the extension reads any local file whose bytes the built-in `read` cannot decode,
+and `file-read` sits beside `file-browse` and `file-open`.
+
+**A table-driven registry** keeps future formats additive, and extracting in
+process means the tool works on any host without a per-format install step and
+without spawning a child process per read.
 
 **Parsers load lazily.** The extension registers on every session, so a static
 top-level import of `exceljs`, `mammoth`, and `unpdf` would tax every startup,
-whether or not a document is ever read. Each extractor therefore imports its
+whether or not a file is ever read. Each extractor therefore imports its
 library inside the call (`await import(...)`), matching `web-access`'s lazy
 `unpdf` import.
 
-**The XLSX format is rebuilt, not passed through.** `exceljs` exposes worksheets
-as objects; the extractor walks every worksheet and reassembles `[Sheet]` + tab
-rows so `read_doc`'s model-facing format is stable across extractor changes and
-every worksheet is included, not just the first.
+**The XLSX text is rebuilt, not passed through.** `exceljs` exposes worksheets as
+objects; the extractor walks every worksheet and reassembles `[Sheet]` + tab rows
+so the model-facing format is stable across extractor changes and every worksheet
+is included, not just the first.
 
-The renderer is unchanged and reuses `context.lastComponent` (`Text.setText`),
-binding the expand hint to `app.tools.expand`. Path shortening lives in
-`render.ts` (not `lib/`): `lib/` helpers are for two or more extensions, and the
-built-in-style `~`/boundary rule here is document-only. The result line
-deliberately omits the path: Pi stacks the call and result lines in one row, so
-repeating it would be pure duplication.
+The renderer reuses `context.lastComponent` (`Text.setText`), binding the expand
+hint to `app.tools.expand`. Path shortening lives in `render.ts` (not `lib/`):
+`lib/` helpers are for two or more extensions, and the built-in-style
+`~`/boundary rule here is this extension's only. The result line deliberately
+omits the path: Pi stacks the call and result lines in one row, so repeating it
+would be pure duplication.
 
 ## Files
 
 | File | Responsibility |
 |---|---|
 | `index.ts` | Factory; registers the tool. |
-| `formats.ts` | `DocumentFormat`, the `FORMATS` registry, `FormatId`, `detectFormat`, `supportedExtensions`, `unsupportedHint`. |
-| `tool.ts` | The tool definition, handler, path guard, extractor override seam, and renderer wiring. Re-exports `TOOL_NAME`. |
+| `formats.ts` | `ReadFormat`, the `FORMATS` registry, `FormatId`, `detectFormat`, `supportedExtensions`, `unsupportedHint`. |
+| `tool.ts` | The tool definition, handler, path guard, extractor override seam, and renderer wiring. |
 | `render.ts` | Theme-aware transcript formatting: call/result lines, `~` + OSC-8 path, expand hint, sanitized preview, and the shared rejection/error path. The call reuses `ToolCallText` (one line, middle clip); the result reuses `Text`. |
-| `schema.ts` | `TOOL_NAME`, `DocParams`, `DocOutput`, limits, result type. |
-| `config.ts` | `DocConfig`, registry-derived defaults, `normalizeConfig`, `loadConfig`, `isFormatEnabled`. |
-| `paging.ts` | `formatDoc`: code-point slicing and header/truncation formatting; `summarizeDoc`: the theme-free transcript summary. |
-| `extract/file.ts` | `DocFile` / `DocExtractor`, `readDocBytes` (abort-aware read), `normalizeBodyText`. |
+| `schema.ts` | `TOOL_NAME`, `ReadParams`, `ReadOutput`, limits, result type. |
+| `config.ts` | `ReadConfig`, registry-derived defaults, `normalizeConfig`, `loadConfig`, `isFormatEnabled`. |
+| `paging.ts` | `formatPage`: code-point slicing and header/truncation formatting; `summarizeRead`: the theme-free transcript summary. |
+| `deadline.ts` | `withDeadline`: abandons a parser that outlasts `extractTimeoutMs` and discards its late result. |
+| `extract/file.ts` | `ExtractInput` / `FormatExtractor`, `readFormatBytes` (abort-aware read), `normalizeBodyText`. |
 | `extract/vendor.d.ts` | Ambient types for `word-extractor` and `rtf-parser` (no bundled declarations). |
 | `extract/pdf.ts` | Adapter over the shared `lib/pdf.ts` seam, plus the PDF body normalization. |
 | `extract/docx.ts` | `mammoth` extractor. |
@@ -291,12 +307,12 @@ repeating it would be pure duplication.
 ## Testing
 
 ```bash
-bun test extensions/document
+bun test extensions/file-read
 ```
 
 Extractor tests run against real minimal files (`test/helpers/fixtures/documents.ts`
 builds a genuine PDF, DOCX, and ODT; XLSX is written with `exceljs`; legacy `.doc`
 reads the committed `files/legacy.doc`), so the libraries are exercised, not
 stubbed. `tool.test.ts` injects fake extractors for behavioural cases and reads a
-real PDF and a real `.doc` end to end; `test/helpers/fixtures/document.ts`
-provides the scratch root and an escape symlink.
+real PDF and a real `.doc` end to end; `test/helpers/fixtures/file-read.ts`
+provides the scratch root and an escape symlink.

package/extensions/{document → file-read}/config.ts

@@ -1,8 +1,8 @@
 /**
- * Configuration for the `document` extension.
+ * Configuration for the `file-read` extension.
  *
  * `formats` defaults are derived from the format registry, so a new format needs
- * no config edit. The `document` section of the shared `bytefly.json` is read
+ * no config edit. The `file-read` section of the shared `bytefly.json` is read
  * from the global document and the project document (project wins), and every
  * field is clamped.
  */
@@ -10,7 +10,7 @@
 import { clampInteger, loadConfigSection } from "../../lib/config.ts";
 import { FORMATS, type FormatId } from "./formats.ts";
 
-export interface DocConfig {
+export interface ReadConfig {
 	/** Reject files larger than this many bytes. */
 	maxFileBytes: number;
 	/** Default character budget for the returned slice. */
@@ -21,7 +21,7 @@ export interface DocConfig {
 	formats: Record<FormatId, boolean>;
 }
 
-export const DEFAULT_CONFIG: DocConfig = {
+export const DEFAULT_CONFIG: ReadConfig = {
 	maxFileBytes: 20 * 1024 * 1024,
 	maxChars: 40_000,
 	extractTimeoutMs: 30_000,
@@ -41,7 +41,10 @@ function normalizeFormats(raw: unknown, base: Record<FormatId, boolean>): Record
 }
 
 /** Validate and clamp a raw config object over the running base. */
-export function normalizeConfig(raw: Record<string, unknown> | undefined, base: DocConfig = DEFAULT_CONFIG): DocConfig {
+export function normalizeConfig(
+	raw: Record<string, unknown> | undefined,
+	base: ReadConfig = DEFAULT_CONFIG,
+): ReadConfig {
 	if (!raw) return base;
 	return {
 		maxFileBytes: clampInteger(raw.maxFileBytes, base.maxFileBytes, 1_024, 512 * 1024 * 1024),
@@ -51,12 +54,12 @@ export function normalizeConfig(raw: Record<string, unknown> | undefined, base:
 	};
 }
 
-/** Effective config from the shared `document` section (defaults, global, project, env). */
-export function loadConfig(cwd: string): DocConfig {
-	return loadConfigSection(cwd, "document", DEFAULT_CONFIG, normalizeConfig);
+/** Effective config from the shared `file-read` section (defaults, global, project, env). */
+export function loadConfig(cwd: string): ReadConfig {
+	return loadConfigSection(cwd, "file-read", DEFAULT_CONFIG, normalizeConfig);
 }
 
 /** Whether a format is enabled in the effective config. */
-export function isFormatEnabled(config: DocConfig, id: FormatId): boolean {
+export function isFormatEnabled(config: ReadConfig, id: FormatId): boolean {
 	return config.formats[id] !== false;
 }

package/extensions/{document → file-read}/extract/doc.ts

@@ -6,10 +6,10 @@
  * is only wired to the `.doc` extension.
  */
 
-import { normalizeBodyText, type DocExtractor } from "./file.ts";
+import { normalizeBodyText, type FormatExtractor } from "./file.ts";
 
 /** Extract the body text from a legacy OLE `.doc` file. */
-export const extractDocText: DocExtractor = async (file) => {
+export const extractDocText: FormatExtractor = async (file) => {
 	file.signal?.throwIfAborted();
 	const module = await import("word-extractor");
 	const extractor = new module.default();

package/extensions/{document → file-read}/extract/docx.ts

@@ -6,11 +6,11 @@
  * part of the body and so are not included.
  */
 
-import { normalizeBodyText, readDocBytes, type DocExtractor } from "./file.ts";
+import { normalizeBodyText, readFormatBytes, type FormatExtractor } from "./file.ts";
 
 /** Extract the body text from a DOCX file. */
-export const extractDocxText: DocExtractor = async (file) => {
-	const bytes = await readDocBytes(file);
+export const extractDocxText: FormatExtractor = async (file) => {
+	const bytes = await readFormatBytes(file);
 	const module = await import("mammoth");
 	const mammoth = module.default;
 	const { value } = await mammoth.extractRawText({ buffer: Buffer.from(bytes) });

package/extensions/{document → file-read}/extract/file.ts

@@ -1,9 +1,9 @@
 /**
  * The in-process extractor contract for `read_doc`.
  *
- * Each document format is extracted by a JavaScript library that reads the file
- * itself. This module owns the file read, the abort check, and the
- * {@link DocExtractor} type, so the format modules stay tiny and testable
+ * Each format is extracted by a JavaScript library that reads the file itself.
+ * This module owns the file read, the abort check, and the
+ * {@link FormatExtractor} type, so the format modules stay tiny and testable
  * through real fixtures.
  *
  * Imports of the extraction libraries are lazy (`await import(...)` inside each
@@ -14,7 +14,7 @@
 import { readFile } from "node:fs/promises";
 
 /** What an extractor receives: the real, root-confined absolute path. */
-export interface DocFile {
+export interface ExtractInput {
 	/** Absolute, symlink-resolved path inside the effective working root. */
 	path: string;
 	/** The active turn's abort signal, checked before any work. */
@@ -22,13 +22,13 @@ export interface DocFile {
 }
 
 /** Extract plain text for one file. */
-export type DocExtractor = (file: DocFile) => Promise<string>;
+export type FormatExtractor = (input: ExtractInput) => Promise<string>;
 
 /** Read the whole file, refusing to start once the turn is aborted. */
-export async function readDocBytes(file: DocFile): Promise<Uint8Array> {
-	file.signal?.throwIfAborted();
-	const bytes = await readFile(file.path);
-	file.signal?.throwIfAborted();
+export async function readFormatBytes(input: ExtractInput): Promise<Uint8Array> {
+	input.signal?.throwIfAborted();
+	const bytes = await readFile(input.path);
+	input.signal?.throwIfAborted();
 	return new Uint8Array(bytes);
 }
 

package/extensions/{document → file-read}/extract/odt.ts

@@ -10,7 +10,7 @@
 
 import { strFromU8, unzipSync } from "fflate";
 import { XMLParser } from "fast-xml-parser";
-import { normalizeBodyText, readDocBytes, type DocExtractor } from "./file.ts";
+import { normalizeBodyText, readFormatBytes, type FormatExtractor } from "./file.ts";
 
 /** Elements that end a line. */
 const BLOCK_ELEMENTS = new Set(["text:p", "text:h", "text:list-item"]);
@@ -93,8 +93,8 @@ export function odtXmlToText(xml: string): string {
 }
 
 /** Extract the body text from an ODT file. */
-export const extractOdtText: DocExtractor = async (file) => {
-	const archive = unzipSync(await readDocBytes(file));
+export const extractOdtText: FormatExtractor = async (file) => {
+	const archive = unzipSync(await readFormatBytes(file));
 	const content = archive["content.xml"];
 	if (!content) throw new Error("ODT archive has no content.xml.");
 	return odtXmlToText(strFromU8(content));

package/extensions/{document → file-read}/extract/pdf.ts

@@ -7,11 +7,11 @@
  */
 
 import { extractPdfText } from "../../../lib/pdf.ts";
-import { readDocBytes, type DocExtractor } from "./file.ts";
+import { readFormatBytes, type FormatExtractor } from "./file.ts";
 
 /** Extract text from every page of a PDF. */
-export const extractPdfDocument: DocExtractor = async (file) => {
-	const bytes = await readDocBytes(file);
+export const extractPdfDocument: FormatExtractor = async (file) => {
+	const bytes = await readFormatBytes(file);
 	const text = await extractPdfText(bytes);
 	return text.replace(/\r\n?/g, "\n").replace(/\n+$/, "");
 };

package/extensions/{document → file-read}/extract/rtf.ts

@@ -6,7 +6,7 @@
  * within a paragraph, paragraphs separated by newlines. Formatting is dropped.
  */
 
-import { normalizeBodyText, readDocBytes, type DocExtractor } from "./file.ts";
+import { normalizeBodyText, readFormatBytes, type FormatExtractor } from "./file.ts";
 
 interface RtfNode {
 	value?: string;
@@ -39,7 +39,7 @@ async function parseRtf(input: string): Promise<RtfDocument> {
 }
 
 /** Extract the body text from an RTF file. */
-export const extractRtfText: DocExtractor = async (file) => {
-	const bytes = await readDocBytes(file);
+export const extractRtfText: FormatExtractor = async (file) => {
+	const bytes = await readFormatBytes(file);
 	return rtfDocumentToText(await parseRtf(new TextDecoder().decode(bytes)));
 };

package/extensions/{document → file-read}/extract/xlsx.ts

@@ -9,7 +9,7 @@
  */
 
 import { stripControlChars } from "../../../lib/format.ts";
-import { readDocBytes, type DocExtractor } from "./file.ts";
+import { readFormatBytes, type FormatExtractor } from "./file.ts";
 
 /** One sheet as the text builder consumes it. */
 interface Sheet {
@@ -60,11 +60,11 @@ export function sheetsToText(value: unknown): string {
 }
 
 /** Extract text from a workbook, one `[Sheet]` section per non-empty worksheet. */
-export const extractXlsxText: DocExtractor = async (file) => {
-	const bytes = await readDocBytes(file);
+export const extractXlsxText: FormatExtractor = async (file) => {
+	const bytes = await readFormatBytes(file);
 	const { Workbook } = await import("exceljs");
 	const workbook = new Workbook();
-	// `readDocBytes` copies into a fresh `Uint8Array`, so its buffer is exactly
+	// `readFormatBytes` copies into a fresh `Uint8Array`, so its buffer is exactly
 	// the file bytes; narrow it for exceljs, which types `load` as ArrayBuffer.
 	const { buffer } = bytes;
 	if (!(buffer instanceof ArrayBuffer)) {