pi-monofold 0.12.5 → 0.12.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +247 -247
- package/package.json +1 -1
- package/workspace-path-lookup.ts +7 -1
package/README.md
CHANGED
|
@@ -1,247 +1,247 @@
|
|
|
1
|
-
# pi-monofold
|
|
2
|
-
|
|
3
|
-
[](https://discord.gg/4945dXZVW5)
|
|
4
|
-
|
|
5
|
-
[](https://github.com/eiei114/pi-monofold/actions/workflows/ci.yml)
|
|
6
|
-
[](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml)
|
|
7
|
-
[](https://www.npmjs.com/package/pi-monofold)
|
|
8
|
-
[](https://www.npmjs.com/package/pi-monofold)
|
|
9
|
-
[](./LICENSE)
|
|
10
|
-
[](https://github.com/eiei114/pi-monofold)
|
|
11
|
-
[](https://docs.npmjs.com/generating-provenance-statements)
|
|
12
|
-
<a href="https://buymeacoffee.com/ekawano114m"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="217" height="60"></a>
|
|
13
|
-
|
|
14
|
-
Pi extension that folds multiple local repositories and folders into a guarded **Virtual Monorepo** for AI agents.
|
|
15
|
-
|
|
16
|
-
## What this is
|
|
17
|
-
|
|
18
|
-
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.
|
|
19
|
-
|
|
20
|
-
See [docs/usage.md](./docs/usage.md) for configuration, commands, agent tools, and guard behavior.
|
|
21
|
-
|
|
22
|
-
## Features
|
|
23
|
-
|
|
24
|
-
- **Virtual monorepo manifest** — declare workspaces and project workspaces in `.pi/monofold.yaml`
|
|
25
|
-
- **Multi-runtime path overlays** — keep one logical workspace definition while swapping absolute repo roots per runtime
|
|
26
|
-
- **Routed Markdown writes** — route PRDs, progress notes, and other doc types to configured folders
|
|
27
|
-
- **Workspace-aware reads** — list, read, search, and tree views scoped to readable workspaces, with bounded previews by default
|
|
28
|
-
- **Capability guard** — block or confirm `read` / `write` / `edit` / `grep` / `find` / `bash` based on workspace tags
|
|
29
|
-
- **Focus presets** — tag-based focus targets for the control workspace
|
|
30
|
-
- **Natural-language commands** — `/monofold:explore`, `/monofold:write`, `/monofold:config`, `/monofold:git`, and more
|
|
31
|
-
- **Strict agent tools** — `monofold_*` tools for programmatic access behind the command surface
|
|
32
|
-
- **Config migration** — upgrade legacy `.pi/monofold.yml` with backups and validation
|
|
33
|
-
|
|
34
|
-
## Install
|
|
35
|
-
|
|
36
|
-
Pi Monofold is a Pi package. Install it with Pi's package installer from git or npm.
|
|
37
|
-
|
|
38
|
-
> Security: Pi packages run with full system access. Review packages before installing third-party code.
|
|
39
|
-
|
|
40
|
-
### From git
|
|
41
|
-
|
|
42
|
-
```powershell
|
|
43
|
-
pi install git:github.com/eiei114/pi-monofold
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
Project-local install:
|
|
47
|
-
|
|
48
|
-
```powershell
|
|
49
|
-
pi install -l git:github.com/eiei114/pi-monofold
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
Pin a version:
|
|
53
|
-
|
|
54
|
-
```powershell
|
|
55
|
-
pi install git:github.com/eiei114/pi-monofold@v0.12.
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
Try without installing:
|
|
59
|
-
|
|
60
|
-
```powershell
|
|
61
|
-
pi -e git:github.com/eiei114/pi-monofold
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
### From npm
|
|
65
|
-
|
|
66
|
-
```powershell
|
|
67
|
-
pi install npm:pi-monofold
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
Project-local install:
|
|
71
|
-
|
|
72
|
-
```powershell
|
|
73
|
-
pi install -l npm:pi-monofold
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
Pin a version:
|
|
77
|
-
|
|
78
|
-
```powershell
|
|
79
|
-
pi install npm:pi-monofold@0.12.
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
Try without installing:
|
|
83
|
-
|
|
84
|
-
```powershell
|
|
85
|
-
pi -e npm:pi-monofold
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
## Quick start
|
|
89
|
-
|
|
90
|
-
1. Install the extension (see [Install](#install)).
|
|
91
|
-
2. In your control repository, create `.pi/monofold.yaml` with at least one workspace entry (or run `/monofold:init`).
|
|
92
|
-
3. Start Pi in the control repository and run `/monofold:explore show the project workspaces`.
|
|
93
|
-
4. Use `/monofold:focus`, `ctrl+shift+m`, or `shift+ctrl+f` to switch focus presets when `focusPresets` are configured. Active Focus is restored automatically on the next Pi session in the same control repository.
|
|
94
|
-
5. Use `/monofold:write` for routed Markdown outputs and `/monofold:git` for guarded git workflows.
|
|
95
|
-
|
|
96
|
-
Example command flows: [docs/examples.md](./docs/examples.md).
|
|
97
|
-
|
|
98
|
-
## Usage summary
|
|
99
|
-
|
|
100
|
-
| Surface | Purpose |
|
|
101
|
-
|---------|---------|
|
|
102
|
-
| `/monofold:explore` | List, read, search, or inspect workspace trees |
|
|
103
|
-
| `/monofold:write` | Create routed Markdown outputs |
|
|
104
|
-
| `/monofold:config` | Add or change workspaces and project workspaces |
|
|
105
|
-
| `/monofold:git` | Run guarded git status, commit, push, or commit+push |
|
|
106
|
-
| `/monofold:focus` | Select the active focus preset from a TUI list |
|
|
107
|
-
| `/monofold:focus-prev` | Cycle Active Focus backward through `focusPresets` YAML order |
|
|
108
|
-
| `/monofold:guide` | Interactive guide for common flows |
|
|
109
|
-
| `/monofold:init` | Create or update `.pi/monofold.yaml` |
|
|
110
|
-
| `/monofold:update` | Migrate legacy config and optionally request config edits |
|
|
111
|
-
|
|
112
|
-
Default focus shortcuts: `ctrl+shift+m` cycles Active Focus forward and `shift+ctrl+f` cycles backward through `focusPresets` YAML order. Both wrap at the start/end of the list.
|
|
113
|
-
|
|
114
|
-
When Active Focus is set, Pi Monofold injects the active preset's `contextFiles` into each agent turn under **Focus Context Injection** and recomposes the manifest so active Workspace Targets are shown first while non-active targets are collapsed to one-line summaries. Tag-based target inference in `monofold_read`, `monofold_write`, and `monofold_git` also prefers Workspace Targets that belong to the active preset when a tag query would otherwise match multiple candidates; explicit `targetId` / workspace name selectors and uniquely matching targets are unchanged. If multiple in-focus targets still tie, the existing workspace selection flow applies. The MVP uses provisional context-injection caps that are intentionally temporary and exposed as constants for future tuning:
|
|
115
|
-
|
|
116
|
-
- Max **6** context files per active preset.
|
|
117
|
-
- Max **6,000** characters per file, with `… [truncated]` appended when a file is cut.
|
|
118
|
-
- Max **12,000** injected file-content characters per turn; remaining files are skipped and a warning is surfaced once for that turn.
|
|
119
|
-
|
|
120
|
-
Agent tools (`monofold_list`, `monofold_read`, `monofold_write`, `monofold_git`, `monofold_init`) sit behind these commands. Use `monofold_list` as the first-line Active Focus health check (preset, route override, unresolved targets, and warnings). Full reference: [docs/usage.md](./docs/usage.md).
|
|
121
|
-
|
|
122
|
-
## Safe read defaults
|
|
123
|
-
|
|
124
|
-
`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.
|
|
125
|
-
|
|
126
|
-
| `monofold_read` mode | Default output |
|
|
127
|
-
|----------------------|----------------|
|
|
128
|
-
| **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. |
|
|
129
|
-
| **search** | Up to **50** match lines and **8,000** characters of ripgrep output. |
|
|
130
|
-
| **tree** | Up to **200** entries; traversal depth is capped at **5**. |
|
|
131
|
-
|
|
132
|
-
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.
|
|
133
|
-
|
|
134
|
-
**Request more content intentionally:**
|
|
135
|
-
|
|
136
|
-
| Goal | `monofold_read` parameters |
|
|
137
|
-
|------|----------------------------|
|
|
138
|
-
| Full file body | `mode: "file"`, `includeContent: true` |
|
|
139
|
-
| Larger bounded file slice | `head`, `tail`, and/or `maxChars` (positive integers) |
|
|
140
|
-
| More search results | Higher `maxMatches` and/or `maxChars`, or a narrower `path` / `query` |
|
|
141
|
-
| Larger directory tree | Higher `maxEntries`, lower `depth`, or a narrower `path` |
|
|
142
|
-
|
|
143
|
-
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).
|
|
144
|
-
|
|
145
|
-
## Package contents
|
|
146
|
-
|
|
147
|
-
```text
|
|
148
|
-
pi-monofold/
|
|
149
|
-
├── .github/workflows/
|
|
150
|
-
│ ├── auto-release.yml # Auto-tag + release on merge to main
|
|
151
|
-
│ ├── ci.yml # Validate on PR / push
|
|
152
|
-
│ └── publish.yml # Publish to npm (Trusted Publishing)
|
|
153
|
-
├── docs/
|
|
154
|
-
│ ├── usage.md # Config, commands, agent API, guard
|
|
155
|
-
│ ├── examples.md # Command examples
|
|
156
|
-
│ └── release.md # Release and publish flow
|
|
157
|
-
├── scripts/
|
|
158
|
-
│ └── check-version-bump.mjs # PR version bump guard (CI)
|
|
159
|
-
├── tests/
|
|
160
|
-
│ ├── file-read-preview.test.ts
|
|
161
|
-
│ ├── focus-command.test.ts
|
|
162
|
-
│ ├── focus-context-injection.test.ts
|
|
163
|
-
│ ├── focus-decision-note-integration.test.ts
|
|
164
|
-
│ ├── focus-decision-note.test.ts
|
|
165
|
-
│ ├── focus-inference-bias.test.ts
|
|
166
|
-
│ ├── focus-preset.test.ts
|
|
167
|
-
│ ├── focus-route-override-integration.test.ts
|
|
168
|
-
│ ├── focus-route-override.test.ts
|
|
169
|
-
│ ├── focus-session-restore.test.ts
|
|
170
|
-
│ ├── focus-session-state.test.ts
|
|
171
|
-
│ ├── focus-skills-auto-load.test.ts
|
|
172
|
-
│ ├── focus-skills.test.ts
|
|
173
|
-
│ ├── changelog-hygiene.test.ts
|
|
174
|
-
│ ├── contributing-docs.test.ts
|
|
175
|
-
│ ├── github-actions-pin.test.ts
|
|
176
|
-
│ ├── monofold-read-caps.test.ts
|
|
177
|
-
│ ├── monofold-read-ops.test.ts
|
|
178
|
-
│ ├── path-normalize.test.ts
|
|
179
|
-
│ ├── readme-package-contents.test.ts
|
|
180
|
-
│ ├── release-docs.test.ts
|
|
181
|
-
│ ├── readme-version-pin.test.ts
|
|
182
|
-
│ ├── runtime-path-overlays.test.ts
|
|
183
|
-
│ ├── tsconfig-publishable-files.test.ts
|
|
184
|
-
│ ├── unknown-path-allows.test.ts
|
|
185
|
-
│ └── workspace-path-lookup.test.ts
|
|
186
|
-
├── CHANGELOG.md
|
|
187
|
-
├── SECURITY.md
|
|
188
|
-
├── file-read-preview.ts
|
|
189
|
-
├── focus-decision-note.ts
|
|
190
|
-
├── focus-preset.ts
|
|
191
|
-
├── focus-route-override.ts
|
|
192
|
-
├── focus-session-state.ts
|
|
193
|
-
├── focus-skills.ts
|
|
194
|
-
├── index.ts
|
|
195
|
-
├── LICENSE
|
|
196
|
-
├── monofold-read-ops.ts
|
|
197
|
-
├── package.json
|
|
198
|
-
├── path-normalize.ts
|
|
199
|
-
├── read-caps.ts
|
|
200
|
-
├── README.md
|
|
201
|
-
├── unknown-path-allows.ts
|
|
202
|
-
├── validation.ts
|
|
203
|
-
├── workspace-path-lookup.ts
|
|
204
|
-
└── tsconfig.json
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
## Development
|
|
208
|
-
|
|
209
|
-
Clone and validate:
|
|
210
|
-
|
|
211
|
-
```powershell
|
|
212
|
-
git clone https://github.com/eiei114/pi-monofold.git
|
|
213
|
-
cd pi-monofold
|
|
214
|
-
npm install
|
|
215
|
-
npm run check
|
|
216
|
-
```
|
|
217
|
-
|
|
218
|
-
Try the local checkout without installing:
|
|
219
|
-
|
|
220
|
-
```powershell
|
|
221
|
-
pi -e .
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
## Release
|
|
225
|
-
|
|
226
|
-
Releases are automated. See [docs/release.md](./docs/release.md) for details.
|
|
227
|
-
|
|
228
|
-
1. Bump `version` in `package.json` and update `CHANGELOG.md`.
|
|
229
|
-
2. Merge to `main`.
|
|
230
|
-
3. **Auto Release** tags `v<version>` and creates a GitHub release when the tag is new.
|
|
231
|
-
4. The tag triggers **Publish**, which publishes to npm with OIDC provenance.
|
|
232
|
-
|
|
233
|
-
## Security
|
|
234
|
-
|
|
235
|
-
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.
|
|
236
|
-
|
|
237
|
-
Report vulnerabilities per [SECURITY.md](./SECURITY.md).
|
|
238
|
-
|
|
239
|
-
## Links
|
|
240
|
-
|
|
241
|
-
- **Repository**: <https://github.com/eiei114/pi-monofold>
|
|
242
|
-
- **npm**: <https://www.npmjs.com/package/pi-monofold>
|
|
243
|
-
- **Issues**: <https://github.com/eiei114/pi-monofold/issues>
|
|
244
|
-
|
|
245
|
-
## License
|
|
246
|
-
|
|
247
|
-
[MIT](LICENSE)
|
|
1
|
+
# pi-monofold
|
|
2
|
+
|
|
3
|
+
[](https://discord.gg/4945dXZVW5)
|
|
4
|
+
|
|
5
|
+
[](https://github.com/eiei114/pi-monofold/actions/workflows/ci.yml)
|
|
6
|
+
[](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml)
|
|
7
|
+
[](https://www.npmjs.com/package/pi-monofold)
|
|
8
|
+
[](https://www.npmjs.com/package/pi-monofold)
|
|
9
|
+
[](./LICENSE)
|
|
10
|
+
[](https://github.com/eiei114/pi-monofold)
|
|
11
|
+
[](https://docs.npmjs.com/generating-provenance-statements)
|
|
12
|
+
<a href="https://buymeacoffee.com/ekawano114m"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="217" height="60"></a>
|
|
13
|
+
|
|
14
|
+
Pi extension that folds multiple local repositories and folders into a guarded **Virtual Monorepo** for AI agents.
|
|
15
|
+
|
|
16
|
+
## What this is
|
|
17
|
+
|
|
18
|
+
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.
|
|
19
|
+
|
|
20
|
+
See [docs/usage.md](./docs/usage.md) for configuration, commands, agent tools, and guard behavior.
|
|
21
|
+
|
|
22
|
+
## Features
|
|
23
|
+
|
|
24
|
+
- **Virtual monorepo manifest** — declare workspaces and project workspaces in `.pi/monofold.yaml`
|
|
25
|
+
- **Multi-runtime path overlays** — keep one logical workspace definition while swapping absolute repo roots per runtime
|
|
26
|
+
- **Routed Markdown writes** — route PRDs, progress notes, and other doc types to configured folders
|
|
27
|
+
- **Workspace-aware reads** — list, read, search, and tree views scoped to readable workspaces, with bounded previews by default
|
|
28
|
+
- **Capability guard** — block or confirm `read` / `write` / `edit` / `grep` / `find` / `bash` based on workspace tags
|
|
29
|
+
- **Focus presets** — tag-based focus targets for the control workspace
|
|
30
|
+
- **Natural-language commands** — `/monofold:explore`, `/monofold:write`, `/monofold:config`, `/monofold:git`, and more
|
|
31
|
+
- **Strict agent tools** — `monofold_*` tools for programmatic access behind the command surface
|
|
32
|
+
- **Config migration** — upgrade legacy `.pi/monofold.yml` with backups and validation
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
Pi Monofold is a Pi package. Install it with Pi's package installer from git or npm.
|
|
37
|
+
|
|
38
|
+
> Security: Pi packages run with full system access. Review packages before installing third-party code.
|
|
39
|
+
|
|
40
|
+
### From git
|
|
41
|
+
|
|
42
|
+
```powershell
|
|
43
|
+
pi install git:github.com/eiei114/pi-monofold
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Project-local install:
|
|
47
|
+
|
|
48
|
+
```powershell
|
|
49
|
+
pi install -l git:github.com/eiei114/pi-monofold
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Pin a version:
|
|
53
|
+
|
|
54
|
+
```powershell
|
|
55
|
+
pi install git:github.com/eiei114/pi-monofold@v0.12.10
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Try without installing:
|
|
59
|
+
|
|
60
|
+
```powershell
|
|
61
|
+
pi -e git:github.com/eiei114/pi-monofold
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### From npm
|
|
65
|
+
|
|
66
|
+
```powershell
|
|
67
|
+
pi install npm:pi-monofold
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Project-local install:
|
|
71
|
+
|
|
72
|
+
```powershell
|
|
73
|
+
pi install -l npm:pi-monofold
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Pin a version:
|
|
77
|
+
|
|
78
|
+
```powershell
|
|
79
|
+
pi install npm:pi-monofold@0.12.10
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Try without installing:
|
|
83
|
+
|
|
84
|
+
```powershell
|
|
85
|
+
pi -e npm:pi-monofold
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Quick start
|
|
89
|
+
|
|
90
|
+
1. Install the extension (see [Install](#install)).
|
|
91
|
+
2. In your control repository, create `.pi/monofold.yaml` with at least one workspace entry (or run `/monofold:init`).
|
|
92
|
+
3. Start Pi in the control repository and run `/monofold:explore show the project workspaces`.
|
|
93
|
+
4. Use `/monofold:focus`, `ctrl+shift+m`, or `shift+ctrl+f` to switch focus presets when `focusPresets` are configured. Active Focus is restored automatically on the next Pi session in the same control repository.
|
|
94
|
+
5. Use `/monofold:write` for routed Markdown outputs and `/monofold:git` for guarded git workflows.
|
|
95
|
+
|
|
96
|
+
Example command flows: [docs/examples.md](./docs/examples.md).
|
|
97
|
+
|
|
98
|
+
## Usage summary
|
|
99
|
+
|
|
100
|
+
| Surface | Purpose |
|
|
101
|
+
|---------|---------|
|
|
102
|
+
| `/monofold:explore` | List, read, search, or inspect workspace trees |
|
|
103
|
+
| `/monofold:write` | Create routed Markdown outputs |
|
|
104
|
+
| `/monofold:config` | Add or change workspaces and project workspaces |
|
|
105
|
+
| `/monofold:git` | Run guarded git status, commit, push, or commit+push |
|
|
106
|
+
| `/monofold:focus` | Select the active focus preset from a TUI list |
|
|
107
|
+
| `/monofold:focus-prev` | Cycle Active Focus backward through `focusPresets` YAML order |
|
|
108
|
+
| `/monofold:guide` | Interactive guide for common flows |
|
|
109
|
+
| `/monofold:init` | Create or update `.pi/monofold.yaml` |
|
|
110
|
+
| `/monofold:update` | Migrate legacy config and optionally request config edits |
|
|
111
|
+
|
|
112
|
+
Default focus shortcuts: `ctrl+shift+m` cycles Active Focus forward and `shift+ctrl+f` cycles backward through `focusPresets` YAML order. Both wrap at the start/end of the list.
|
|
113
|
+
|
|
114
|
+
When Active Focus is set, Pi Monofold injects the active preset's `contextFiles` into each agent turn under **Focus Context Injection** and recomposes the manifest so active Workspace Targets are shown first while non-active targets are collapsed to one-line summaries. Tag-based target inference in `monofold_read`, `monofold_write`, and `monofold_git` also prefers Workspace Targets that belong to the active preset when a tag query would otherwise match multiple candidates; explicit `targetId` / workspace name selectors and uniquely matching targets are unchanged. If multiple in-focus targets still tie, the existing workspace selection flow applies. The MVP uses provisional context-injection caps that are intentionally temporary and exposed as constants for future tuning:
|
|
115
|
+
|
|
116
|
+
- Max **6** context files per active preset.
|
|
117
|
+
- Max **6,000** characters per file, with `… [truncated]` appended when a file is cut.
|
|
118
|
+
- Max **12,000** injected file-content characters per turn; remaining files are skipped and a warning is surfaced once for that turn.
|
|
119
|
+
|
|
120
|
+
Agent tools (`monofold_list`, `monofold_read`, `monofold_write`, `monofold_git`, `monofold_init`) sit behind these commands. Use `monofold_list` as the first-line Active Focus health check (preset, route override, unresolved targets, and warnings). Full reference: [docs/usage.md](./docs/usage.md).
|
|
121
|
+
|
|
122
|
+
## Safe read defaults
|
|
123
|
+
|
|
124
|
+
`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.
|
|
125
|
+
|
|
126
|
+
| `monofold_read` mode | Default output |
|
|
127
|
+
|----------------------|----------------|
|
|
128
|
+
| **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. |
|
|
129
|
+
| **search** | Up to **50** match lines and **8,000** characters of ripgrep output. |
|
|
130
|
+
| **tree** | Up to **200** entries; traversal depth is capped at **5**. |
|
|
131
|
+
|
|
132
|
+
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.
|
|
133
|
+
|
|
134
|
+
**Request more content intentionally:**
|
|
135
|
+
|
|
136
|
+
| Goal | `monofold_read` parameters |
|
|
137
|
+
|------|----------------------------|
|
|
138
|
+
| Full file body | `mode: "file"`, `includeContent: true` |
|
|
139
|
+
| Larger bounded file slice | `head`, `tail`, and/or `maxChars` (positive integers) |
|
|
140
|
+
| More search results | Higher `maxMatches` and/or `maxChars`, or a narrower `path` / `query` |
|
|
141
|
+
| Larger directory tree | Higher `maxEntries`, lower `depth`, or a narrower `path` |
|
|
142
|
+
|
|
143
|
+
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).
|
|
144
|
+
|
|
145
|
+
## Package contents
|
|
146
|
+
|
|
147
|
+
```text
|
|
148
|
+
pi-monofold/
|
|
149
|
+
├── .github/workflows/
|
|
150
|
+
│ ├── auto-release.yml # Auto-tag + release on merge to main
|
|
151
|
+
│ ├── ci.yml # Validate on PR / push
|
|
152
|
+
│ └── publish.yml # Publish to npm (Trusted Publishing)
|
|
153
|
+
├── docs/
|
|
154
|
+
│ ├── usage.md # Config, commands, agent API, guard
|
|
155
|
+
│ ├── examples.md # Command examples
|
|
156
|
+
│ └── release.md # Release and publish flow
|
|
157
|
+
├── scripts/
|
|
158
|
+
│ └── check-version-bump.mjs # PR version bump guard (CI)
|
|
159
|
+
├── tests/
|
|
160
|
+
│ ├── file-read-preview.test.ts
|
|
161
|
+
│ ├── focus-command.test.ts
|
|
162
|
+
│ ├── focus-context-injection.test.ts
|
|
163
|
+
│ ├── focus-decision-note-integration.test.ts
|
|
164
|
+
│ ├── focus-decision-note.test.ts
|
|
165
|
+
│ ├── focus-inference-bias.test.ts
|
|
166
|
+
│ ├── focus-preset.test.ts
|
|
167
|
+
│ ├── focus-route-override-integration.test.ts
|
|
168
|
+
│ ├── focus-route-override.test.ts
|
|
169
|
+
│ ├── focus-session-restore.test.ts
|
|
170
|
+
│ ├── focus-session-state.test.ts
|
|
171
|
+
│ ├── focus-skills-auto-load.test.ts
|
|
172
|
+
│ ├── focus-skills.test.ts
|
|
173
|
+
│ ├── changelog-hygiene.test.ts
|
|
174
|
+
│ ├── contributing-docs.test.ts
|
|
175
|
+
│ ├── github-actions-pin.test.ts
|
|
176
|
+
│ ├── monofold-read-caps.test.ts
|
|
177
|
+
│ ├── monofold-read-ops.test.ts
|
|
178
|
+
│ ├── path-normalize.test.ts
|
|
179
|
+
│ ├── readme-package-contents.test.ts
|
|
180
|
+
│ ├── release-docs.test.ts
|
|
181
|
+
│ ├── readme-version-pin.test.ts
|
|
182
|
+
│ ├── runtime-path-overlays.test.ts
|
|
183
|
+
│ ├── tsconfig-publishable-files.test.ts
|
|
184
|
+
│ ├── unknown-path-allows.test.ts
|
|
185
|
+
│ └── workspace-path-lookup.test.ts
|
|
186
|
+
├── CHANGELOG.md
|
|
187
|
+
├── SECURITY.md
|
|
188
|
+
├── file-read-preview.ts
|
|
189
|
+
├── focus-decision-note.ts
|
|
190
|
+
├── focus-preset.ts
|
|
191
|
+
├── focus-route-override.ts
|
|
192
|
+
├── focus-session-state.ts
|
|
193
|
+
├── focus-skills.ts
|
|
194
|
+
├── index.ts
|
|
195
|
+
├── LICENSE
|
|
196
|
+
├── monofold-read-ops.ts
|
|
197
|
+
├── package.json
|
|
198
|
+
├── path-normalize.ts
|
|
199
|
+
├── read-caps.ts
|
|
200
|
+
├── README.md
|
|
201
|
+
├── unknown-path-allows.ts
|
|
202
|
+
├── validation.ts
|
|
203
|
+
├── workspace-path-lookup.ts
|
|
204
|
+
└── tsconfig.json
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
## Development
|
|
208
|
+
|
|
209
|
+
Clone and validate:
|
|
210
|
+
|
|
211
|
+
```powershell
|
|
212
|
+
git clone https://github.com/eiei114/pi-monofold.git
|
|
213
|
+
cd pi-monofold
|
|
214
|
+
npm install
|
|
215
|
+
npm run check
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Try the local checkout without installing:
|
|
219
|
+
|
|
220
|
+
```powershell
|
|
221
|
+
pi -e .
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
## Release
|
|
225
|
+
|
|
226
|
+
Releases are automated. See [docs/release.md](./docs/release.md) for details.
|
|
227
|
+
|
|
228
|
+
1. Bump `version` in `package.json` and update `CHANGELOG.md`.
|
|
229
|
+
2. Merge to `main`.
|
|
230
|
+
3. **Auto Release** tags `v<version>` and creates a GitHub release when the tag is new.
|
|
231
|
+
4. The tag triggers **Publish**, which publishes to npm with OIDC provenance.
|
|
232
|
+
|
|
233
|
+
## Security
|
|
234
|
+
|
|
235
|
+
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.
|
|
236
|
+
|
|
237
|
+
Report vulnerabilities per [SECURITY.md](./SECURITY.md).
|
|
238
|
+
|
|
239
|
+
## Links
|
|
240
|
+
|
|
241
|
+
- **Repository**: <https://github.com/eiei114/pi-monofold>
|
|
242
|
+
- **npm**: <https://www.npmjs.com/package/pi-monofold>
|
|
243
|
+
- **Issues**: <https://github.com/eiei114/pi-monofold/issues>
|
|
244
|
+
|
|
245
|
+
## License
|
|
246
|
+
|
|
247
|
+
[MIT](LICENSE)
|
package/package.json
CHANGED
package/workspace-path-lookup.ts
CHANGED
|
@@ -41,5 +41,11 @@ export function findWorkspaceForAbsolutePath<T extends { resolvedPath: string }>
|
|
|
41
41
|
): T | undefined {
|
|
42
42
|
const impl = selectPathImpl(absolutePath, ...pathLookupWorkspaces.map((workspace) => workspace.resolvedPath));
|
|
43
43
|
const absolute = normalizeGuardPath(absolutePath, impl);
|
|
44
|
-
return pathLookupWorkspaces.find((workspace) =>
|
|
44
|
+
return pathLookupWorkspaces.find((workspace) => {
|
|
45
|
+
const relative = impl.relative(normalizeGuardPath(workspace.resolvedPath, impl), absolute);
|
|
46
|
+
return (
|
|
47
|
+
relative === "" ||
|
|
48
|
+
(relative !== ".." && !relative.startsWith(`..${impl.sep}`) && !impl.isAbsolute(relative))
|
|
49
|
+
);
|
|
50
|
+
});
|
|
45
51
|
}
|