pi-monofold 0.3.1 → 0.3.3

package/README.md

@@ -1,172 +1,195 @@
-# pi-monofold
-
-[![CI](https://github.com/eiei114/pi-monofold/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-monofold/actions/workflows/ci.yml)
-[![Publish](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml)
-[![npm version](https://img.shields.io/npm/v/pi-monofold?color=cb3837&logo=npm)](https://www.npmjs.com/package/pi-monofold)
-[![npm downloads](https://img.shields.io/npm/dw/pi-monofold)](https://www.npmjs.com/package/pi-monofold)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Pi Package](https://img.shields.io/badge/Pi-package-6f42c1)](https://github.com/eiei114/pi-monofold)
-[![Trusted Publishing](https://img.shields.io/badge/npm-provenance-yellow)](https://docs.npmjs.com/generating-provenance-statements)
-
-Pi extension that folds multiple local repositories and folders into a guarded **Virtual Monorepo** for AI agents.
-
-## What this is
-
-Pi Monofold (`pi-monofold`) keeps repositories physically separate while giving Pi a lightweight manifest, routed writes, workspace-aware reads, guarded commands, and explicit git flows. Documentation, rules, product context, and implementation code can appear as one connected system without migrating everything into a single git repository.
-
-See [docs/usage.md](./docs/usage.md) for configuration, commands, agent tools, and guard behavior.
-
-## Features
-
-- **Virtual monorepo manifest** — declare workspaces and project workspaces in `.pi/monofold.yaml`
-- **Routed Markdown writes** — route PRDs, progress notes, and other doc types to configured folders
-- **Workspace-aware reads** — list, read, search, and tree views scoped to readable workspaces
-- **Capability guard** — block or confirm `read` / `write` / `edit` / `grep` / `find` / `bash` based on workspace tags
-- **Focus presets** — tag-based focus targets for the control workspace
-- **Natural-language commands** — `/monofold:explore`, `/monofold:write`, `/monofold:config`, `/monofold:git`, and more
-- **Strict agent tools** — `monofold_*` tools for programmatic access behind the command surface
-- **Config migration** — upgrade legacy `.pi/monofold.yml` with backups and validation
-
-## Install
-
-Pi Monofold is a Pi package. Install it with Pi's package installer from git or npm.
-
-> Security: Pi packages run with full system access. Review packages before installing third-party code.
-
-### From git
-
-```powershell
-pi install git:github.com/eiei114/pi-monofold
-```
-
-Project-local install:
-
-```powershell
-pi install -l git:github.com/eiei114/pi-monofold
-```
-
-Pin a version:
-
-```powershell
-pi install git:github.com/eiei114/pi-monofold@v0.3.1
-```
-
-Try without installing:
-
-```powershell
-pi -e git:github.com/eiei114/pi-monofold
-```
-
-### From npm
-
-```powershell
-pi install npm:pi-monofold
-```
-
-Project-local install:
-
-```powershell
-pi install -l npm:pi-monofold
-```
-
-Pin a version:
-
-```powershell
-pi install npm:pi-monofold@0.3.1
-```
-
-Try without installing:
-
-```powershell
-pi -e npm:pi-monofold
-```
-
-## Quick start
-
-1. Install the extension (see [Install](#install)).
-2. In your control repository, create `.pi/monofold.yaml` with at least one workspace entry (or run `/monofold:init`).
-3. Start Pi in the control repository and run `/monofold:explore show the project workspaces`.
-4. Use `/monofold:write` for routed Markdown outputs and `/monofold:git` for guarded git workflows.
-
-Example command flows: [docs/examples.md](./docs/examples.md).
-
-## Usage summary
-
-| Surface | Purpose |
-|---------|---------|
-| `/monofold:explore` | List, read, search, or inspect workspace trees |
-| `/monofold:write` | Create routed Markdown outputs |
-| `/monofold:config` | Add or change workspaces and project workspaces |
-| `/monofold:git` | Run guarded git status, commit, push, or commit+push |
-| `/monofold:guide` | Interactive guide for common flows |
-| `/monofold:init` | Create or update `.pi/monofold.yaml` |
-| `/monofold:update` | Migrate legacy config and optionally request config edits |
-
-Agent tools (`monofold_list`, `monofold_read`, `monofold_write`, `monofold_git`, `monofold_init`) sit behind these commands. Full reference: [docs/usage.md](./docs/usage.md).
-
-## Package contents
-
-```text
-pi-monofold/
-├── .github/workflows/
-│   ├── auto-release.yml            # Auto-tag + release on merge to main
-│   ├── ci.yml                      # Validate on PR / push
-│   └── publish.yml                 # Publish to npm (Trusted Publishing)
-├── docs/
-│   ├── usage.md                    # Config, commands, agent API, guard
-│   ├── examples.md                 # Command examples
-│   └── release.md                  # Release and publish flow
-├── tests/
-│   └── focus-preset.test.ts
-├── CHANGELOG.md
-├── SECURITY.md
-├── focus-preset.ts
-├── index.ts
-├── LICENSE
-├── package.json
-├── README.md
-├── validation.ts
-└── tsconfig.json
-```
-
-## Development
-
-Clone and validate:
-
-```powershell
-git clone https://github.com/eiei114/pi-monofold.git
-cd pi-monofold
-npm install
-npm run check
-```
-
-Try the local checkout without installing:
-
-```powershell
-pi -e .
-```
-
-## Release
-
-Releases are automated. See [docs/release.md](./docs/release.md) for details.
-
-1. Bump `version` in `package.json` and update `CHANGELOG.md`.
-2. Merge to `main`.
-3. **Auto Release** tags `v<version>` and creates a GitHub release when the tag is new.
-4. The tag triggers **Publish**, which publishes to npm with OIDC provenance.
-
-## Security
-
-Pi Monofold intercepts standard Pi tool calls when monofold config is present. Writes and shell commands are allowed only when the resolved workspace grants the matching capability. Git commit/push via raw `bash` is blocked; use `/monofold:git` or `monofold_git` instead.
-
-Report vulnerabilities per [SECURITY.md](./SECURITY.md).
-
-## Links
-
-- **Repository**: <https://github.com/eiei114/pi-monofold>
-- **npm**: <https://www.npmjs.com/package/pi-monofold>
-- **Issues**: <https://github.com/eiei114/pi-monofold/issues>
-
-## License
-
-[MIT](LICENSE)
+# pi-monofold
+
+[![CI](https://github.com/eiei114/pi-monofold/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-monofold/actions/workflows/ci.yml)
+[![Publish](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml)
+[![npm version](https://img.shields.io/npm/v/pi-monofold?color=cb3837&logo=npm)](https://www.npmjs.com/package/pi-monofold)
+[![npm downloads](https://img.shields.io/npm/dw/pi-monofold)](https://www.npmjs.com/package/pi-monofold)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Pi Package](https://img.shields.io/badge/Pi-package-6f42c1)](https://github.com/eiei114/pi-monofold)
+[![Trusted Publishing](https://img.shields.io/badge/npm-provenance-yellow)](https://docs.npmjs.com/generating-provenance-statements)
+
+Pi extension that folds multiple local repositories and folders into a guarded **Virtual Monorepo** for AI agents.
+
+## What this is
+
+Pi Monofold (`pi-monofold`) keeps repositories physically separate while giving Pi a lightweight manifest, routed writes, workspace-aware reads, guarded commands, and explicit git flows. Documentation, rules, product context, and implementation code can appear as one connected system without migrating everything into a single git repository.
+
+See [docs/usage.md](./docs/usage.md) for configuration, commands, agent tools, and guard behavior.
+
+## Features
+
+- **Virtual monorepo manifest** — declare workspaces and project workspaces in `.pi/monofold.yaml`
+- **Routed Markdown writes** — route PRDs, progress notes, and other doc types to configured folders
+- **Workspace-aware reads** — list, read, search, and tree views scoped to readable workspaces, with bounded previews by default
+- **Capability guard** — block or confirm `read` / `write` / `edit` / `grep` / `find` / `bash` based on workspace tags
+- **Focus presets** — tag-based focus targets for the control workspace
+- **Natural-language commands** — `/monofold:explore`, `/monofold:write`, `/monofold:config`, `/monofold:git`, and more
+- **Strict agent tools** — `monofold_*` tools for programmatic access behind the command surface
+- **Config migration** — upgrade legacy `.pi/monofold.yml` with backups and validation
+
+## Install
+
+Pi Monofold is a Pi package. Install it with Pi's package installer from git or npm.
+
+> Security: Pi packages run with full system access. Review packages before installing third-party code.
+
+### From git
+
+```powershell
+pi install git:github.com/eiei114/pi-monofold
+```
+
+Project-local install:
+
+```powershell
+pi install -l git:github.com/eiei114/pi-monofold
+```
+
+Pin a version:
+
+```powershell
+pi install git:github.com/eiei114/pi-monofold@v0.3.2
+```
+
+Try without installing:
+
+```powershell
+pi -e git:github.com/eiei114/pi-monofold
+```
+
+### From npm
+
+```powershell
+pi install npm:pi-monofold
+```
+
+Project-local install:
+
+```powershell
+pi install -l npm:pi-monofold
+```
+
+Pin a version:
+
+```powershell
+pi install npm:pi-monofold@0.3.2
+```
+
+Try without installing:
+
+```powershell
+pi -e npm:pi-monofold
+```
+
+## Quick start
+
+1. Install the extension (see [Install](#install)).
+2. In your control repository, create `.pi/monofold.yaml` with at least one workspace entry (or run `/monofold:init`).
+3. Start Pi in the control repository and run `/monofold:explore show the project workspaces`.
+4. Use `/monofold:write` for routed Markdown outputs and `/monofold:git` for guarded git workflows.
+
+Example command flows: [docs/examples.md](./docs/examples.md).
+
+## Usage summary
+
+| Surface | Purpose |
+|---------|---------|
+| `/monofold:explore` | List, read, search, or inspect workspace trees |
+| `/monofold:write` | Create routed Markdown outputs |
+| `/monofold:config` | Add or change workspaces and project workspaces |
+| `/monofold:git` | Run guarded git status, commit, push, or commit+push |
+| `/monofold:guide` | Interactive guide for common flows |
+| `/monofold:init` | Create or update `.pi/monofold.yaml` |
+| `/monofold:update` | Migrate legacy config and optionally request config edits |
+
+Agent tools (`monofold_list`, `monofold_read`, `monofold_write`, `monofold_git`, `monofold_init`) sit behind these commands. Full reference: [docs/usage.md](./docs/usage.md).
+
+## Safe read defaults
+
+`monofold_read` can reach files across multiple configured workspaces. Returning full file bodies or unbounded search/tree output by default would flood the agent chat and can bias later turns. Pi Monofold therefore uses **preview-first, capped-by-default** reads.
+
+| `monofold_read` mode | Default output |
+|----------------------|----------------|
+| **file** | Path, size, line/character counts, modified time, then a bounded preview (first **20** lines, up to **2,000** characters). Files that already fit those bounds are shown in full without a truncation marker. |
+| **search** | Up to **50** match lines and **8,000** characters of ripgrep output. |
+| **tree** | Up to **200** entries; traversal depth is capped at **5**. |
+
+When output is cut, the tool response includes a **`[truncated]`** marker (file mode) or a **`[truncated: …]`** footer (search/tree) that states what was shown and how to request more.
+
+**Request more content intentionally:**
+
+| Goal | `monofold_read` parameters |
+|------|----------------------------|
+| Full file body | `mode: "file"`, `includeContent: true` |
+| Larger bounded file slice | `head`, `tail`, and/or `maxChars` (positive integers) |
+| More search results | Higher `maxMatches` and/or `maxChars`, or a narrower `path` / `query` |
+| Larger directory tree | Higher `maxEntries`, lower `depth`, or a narrower `path` |
+
+Agents should call **`monofold_read`** (not guess at raw Pi `read`). Humans should use **`/monofold:explore`** with natural language. Legacy slash commands such as `/monofold:read` apply the same caps for compatibility but are **not** the preferred human-facing surface—see [docs/usage.md](./docs/usage.md#safe-read-contract-monofold_read).
+
+## Package contents
+
+```text
+pi-monofold/
+├── .github/workflows/
+│   ├── auto-release.yml            # Auto-tag + release on merge to main
+│   ├── ci.yml                      # Validate on PR / push
+│   └── publish.yml                 # Publish to npm (Trusted Publishing)
+├── docs/
+│   ├── usage.md                    # Config, commands, agent API, guard
+│   ├── examples.md                 # Command examples
+│   └── release.md                  # Release and publish flow
+├── tests/
+│   └── focus-preset.test.ts
+├── CHANGELOG.md
+├── SECURITY.md
+├── focus-preset.ts
+├── index.ts
+├── LICENSE
+├── package.json
+├── README.md
+├── validation.ts
+└── tsconfig.json
+```
+
+## Development
+
+Clone and validate:
+
+```powershell
+git clone https://github.com/eiei114/pi-monofold.git
+cd pi-monofold
+npm install
+npm run check
+```
+
+Try the local checkout without installing:
+
+```powershell
+pi -e .
+```
+
+## Release
+
+Releases are automated. See [docs/release.md](./docs/release.md) for details.
+
+1. Bump `version` in `package.json` and update `CHANGELOG.md`.
+2. Merge to `main`.
+3. **Auto Release** tags `v<version>` and creates a GitHub release when the tag is new.
+4. The tag triggers **Publish**, which publishes to npm with OIDC provenance.
+
+## Security
+
+Pi Monofold intercepts standard Pi tool calls when monofold config is present. Writes and shell commands are allowed only when the resolved workspace grants the matching capability. Git commit/push via raw `bash` is blocked; use `/monofold:git` or `monofold_git` instead.
+
+Report vulnerabilities per [SECURITY.md](./SECURITY.md).
+
+## Links
+
+- **Repository**: <https://github.com/eiei114/pi-monofold>
+- **npm**: <https://www.npmjs.com/package/pi-monofold>
+- **Issues**: <https://github.com/eiei114/pi-monofold/issues>
+
+## License
+
+[MIT](LICENSE)

package/file-read-preview.ts

@@ -0,0 +1,208 @@
+export const DEFAULT_PREVIEW_LINES = 20;
+export const DEFAULT_PREVIEW_CHARS = 2_000;
+
+export type FileReadOptions = {
+  includeContent?: boolean;
+  maxChars?: number;
+  head?: number;
+  tail?: number;
+};
+
+export type FileReadFileStat = {
+  size: number;
+  mtime: Date;
+};
+
+export type FileReadDetails = {
+  byteSize: number;
+  characterCount: number;
+  lineCount: number;
+  modifiedTime: string;
+  truncated: boolean;
+  previewLineCount: number;
+  previewCharacterCount: number;
+  includeContent: boolean;
+  maxChars?: number;
+  head?: number;
+  tail?: number;
+};
+
+export type FileReadResponse = {
+  text: string;
+  details: FileReadDetails;
+};
+
+export function assertPositiveInt(value: number, label: string): number {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return value;
+}
+
+function splitLines(content: string): string[] {
+  if (content.length === 0) {
+    return [""];
+  }
+  const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const lines = normalized.split("\n");
+  if (lines.at(-1) === "" && (content.endsWith("\n") || content.endsWith("\r"))) {
+    lines.pop();
+  }
+  return lines.length === 0 ? [""] : lines;
+}
+
+function takeHeadLines(lines: string[], count: number): string[] {
+  return lines.slice(0, count);
+}
+
+function takeTailLines(lines: string[], count: number): string[] {
+  if (count >= lines.length) {
+    return lines;
+  }
+  return lines.slice(lines.length - count);
+}
+
+function truncateChars(text: string, maxChars: number): { text: string; truncated: boolean } {
+  if (text.length <= maxChars) {
+    return { text, truncated: false };
+  }
+  return { text: text.slice(0, maxChars), truncated: true };
+}
+
+export function truncationHint(details: FileReadDetails): string {
+  const parts: string[] = [];
+  if (details.truncated) {
+    parts.push(
+      `Showing ${details.previewLineCount} of ${details.lineCount} lines and ${details.previewCharacterCount} of ${details.characterCount} characters.`,
+    );
+  }
+  parts.push(
+    "Pass includeContent: true for full content, or use head, tail, and/or maxChars for a larger bounded range.",
+  );
+  return parts.join(" ");
+}
+
+function buildHeadTailPreview(lines: string[], head: number | undefined, tail: number | undefined): string {
+  const headCount = head ?? 0;
+  const tailCount = tail ?? 0;
+  if (headCount > 0 && tailCount > 0) {
+    const headLines = takeHeadLines(lines, headCount);
+    const tailLines = takeTailLines(lines, tailCount);
+    if (headCount + tailCount >= lines.length) {
+      return lines.join("\n");
+    }
+    const omitted = lines.length - headLines.length - tailLines.length;
+    return [
+      ...headLines,
+      `... [${omitted} line${omitted === 1 ? "" : "s"} omitted] ...`,
+      ...tailLines,
+    ].join("\n");
+  }
+  if (headCount > 0) {
+    return takeHeadLines(lines, headCount).join("\n");
+  }
+  if (tailCount > 0) {
+    return takeTailLines(lines, tailCount).join("\n");
+  }
+  return takeHeadLines(lines, DEFAULT_PREVIEW_LINES).join("\n");
+}
+
+function resolveExplicitLimits(options: FileReadOptions): {
+  includeContent: boolean;
+  maxChars?: number;
+  head?: number;
+  tail?: number;
+} {
+  const includeContent = options.includeContent === true;
+  const maxChars = options.maxChars === undefined ? undefined : assertPositiveInt(options.maxChars, "maxChars");
+  const head = options.head === undefined ? undefined : assertPositiveInt(options.head, "head");
+  const tail = options.tail === undefined ? undefined : assertPositiveInt(options.tail, "tail");
+  return { includeContent, maxChars, head, tail };
+}
+
+export function buildFileReadResponse(
+  content: string,
+  options: FileReadOptions,
+  fileStat: FileReadFileStat,
+  context: { relativePath: string },
+): FileReadResponse {
+  const limits = resolveExplicitLimits(options);
+  const lines = splitLines(content);
+  const lineCount = lines.length;
+  const characterCount = content.length;
+
+  let previewText: string;
+  let truncated: boolean;
+  let previewLineCount: number;
+  let previewCharacterCount: number;
+
+  if (limits.includeContent && limits.maxChars === undefined && limits.head === undefined && limits.tail === undefined) {
+    previewText = content;
+    truncated = false;
+    previewLineCount = lineCount;
+    previewCharacterCount = characterCount;
+  } else if (limits.head !== undefined || limits.tail !== undefined) {
+    const headCount = limits.head ?? 0;
+    const tailCount = limits.tail ?? 0;
+    previewText = buildHeadTailPreview(lines, limits.head, limits.tail);
+    const maxChars = limits.maxChars ?? Number.POSITIVE_INFINITY;
+    const charResult = truncateChars(previewText, maxChars);
+    previewText = charResult.text;
+    const linesFullyShown =
+      headCount + tailCount >= lineCount ||
+      (headCount > 0 && tailCount === 0 && headCount >= lineCount) ||
+      (tailCount > 0 && headCount === 0 && tailCount >= lineCount);
+    truncated = charResult.truncated || !linesFullyShown;
+    previewLineCount = previewText === "" ? 0 : previewText.split("\n").length;
+    previewCharacterCount = previewText.length;
+  } else if (limits.maxChars !== undefined) {
+    const charResult = truncateChars(content, limits.maxChars);
+    previewText = charResult.text;
+    truncated = charResult.truncated || previewText.length < content.length;
+    previewLineCount = previewText === "" ? 0 : previewText.split("\n").length;
+    previewCharacterCount = previewText.length;
+  } else {
+    const defaultLines = takeHeadLines(lines, DEFAULT_PREVIEW_LINES);
+    previewText = defaultLines.join("\n");
+    const charResult = truncateChars(previewText, DEFAULT_PREVIEW_CHARS);
+    previewText = charResult.text;
+    truncated = charResult.truncated || defaultLines.length < lines.length;
+    previewLineCount = previewText === "" ? 0 : previewText.split("\n").length;
+    previewCharacterCount = previewText.length;
+  }
+
+  const details: FileReadDetails = {
+    byteSize: fileStat.size,
+    characterCount,
+    lineCount,
+    modifiedTime: fileStat.mtime.toISOString(),
+    truncated,
+    previewLineCount,
+    previewCharacterCount,
+    includeContent: limits.includeContent,
+    ...(limits.maxChars === undefined ? {} : { maxChars: limits.maxChars }),
+    ...(limits.head === undefined ? {} : { head: limits.head }),
+    ...(limits.tail === undefined ? {} : { tail: limits.tail }),
+  };
+
+  const metadataLines = [
+    `Path: ${context.relativePath}`,
+    `Byte size: ${details.byteSize}`,
+    `Characters: ${details.characterCount}`,
+    `Lines: ${details.lineCount}`,
+    `Modified: ${details.modifiedTime}`,
+  ];
+
+  const sections = [metadataLines.join("\n")];
+  if (previewText.length > 0) {
+    sections.push("", "--- preview ---", previewText);
+  }
+  if (truncated) {
+    sections.push("", `[truncated] ${truncationHint(details)}`);
+  }
+
+  return {
+    text: sections.join("\n"),
+    details,
+  };
+}