repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

llmiterate: prioritize order of section in README

1e080b77998d6630003fb8c871c7924ed7d96e3c

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

extensions/llmiterate/README.md

Modified
1 +<!-- !llmiterate -->
1 3 # llmiterate
3 5 Manual editor-save bridge from comment markers to background Pi edits.
7 +## Behavior
9 +llmiterate does not autostart.
10 +`/llmiterate` or `/llmiterate on` starts it for the exact real cwd.
11 +It loads global Pi settings, then `<scope>/.pi/settings.json`; there is no
12 +upward project-root search.
14 +Start sequence:
16 +1. resolve cwd
17 +2. load config and state
18 +3. acquire singleton lock for the scope hash
19 +4. start watcher
20 +5. run initial scan
21 +6. queue matching markers
23 +## Marker syntax
25 +One marker only:
27 +```text
28 +llmiterate:
29 +```
31 +Marker must appear after a known comment prefix.
32 +Raw markers never run.
34 +```java
35 +void main(final String[] a) {
36 + // llmiterate: implement argument validation
37 + if (a.length == 0) {
38 + // llmiterate: print usage and exit non-zero
39 + }
41 +```
43 +```py
44 +def parse(src):
45 + # llmiterate: implement parser fast path
46 +```
48 +```sql
49 +-- llmiterate: add index for lookup query
51 +```
53 +Rules:
55 +- raw `llmiterate:` is ignored
56 +- consecutive marker lines are grouped
57 +- empty marker lines are ignored
58 +- `!llmiterate` in a comment disables the whole file
60 +## Comment prefixes
62 +Prefixes are extension-scoped.
63 +Built-ins include:
65 +| file type | prefix |
66 +| ----------------------------------------------------------------------------------------- | ----------------- |
67 +| .c/.cc/.cpp/.cs/.cts/.go/.h/.hpp/.java/.js/.jsx/.kt/.kts/.mts/.php/.scala/.swift/.ts/.tsx | // /// /* /** |
68 +| .rs | // /// //! /* /** |
69 +| .css | /* /** |
70 +| .scss/.less | // /* /** |
71 +| .py/.sh/.bash/.zsh/.fish/.rb/.pl/.pm/.r/.toml/.yaml/.yml/.dockerfile/.ex/.exs | # |
72 +| .md/.mdx/.html/.htm/.xml | <!-- --> |
73 +| .sql/.lua/.hs | -- |
74 +| .lisp/.el/.clj/.scm | ; ;; ;;; |
75 +| .tex | % %% |
76 +| .erl | % |
77 +| .f/.f90 | ! |
79 +Unknown extensions do not run markers.
80 +Markdown only accepts HTML comments, so headings or bullets containing
81 +`llmiterate:` are inert.
83 +Config `commentPrefixes` appends by extension:
85 +```json
87 + "llmiterate": {
88 + "commentPrefixes": {
89 + "foo": ["COMMENT"],
90 + "lua": ["--"]
91 + }
92 + }
94 +```
96 +## Replacement behavior
98 +For each marker block, the worker receives a prompt containing:
100 +- source location:
101 + `@file:startLine`
102 +- marker text
103 +- marker span to replace
104 +- instruction to work in/around the file
105 +- instruction to remove the marker unless impossible
107 +Before a job starts, llmiterate rechecks that the marker still exists at the
108 +same line with the same prompt hash.
109 +If it changed, the job is failed as stale and skipped.
111 +After the worker finishes, llmiterate rechecks the file.
112 +If the same marker is still present at the same line with the same prompt hash,
113 +the job is marked failed.
114 +Otherwise that job is marked done.
5 116 ## Install / load
7 118 This extension is loaded through the root pi-ext package.
60 171 ```json
62 - "llmiterate": {
63 - "enabled": true,
64 - "include": ["src/**/*.{ts,tsx,rs,java,md}", "docs/**/*.md"],
65 - "exclude": ["**/target/**", "**/dist/**"],
66 - "debounceMs": 3000,
67 - "maxFileBytes": 1000000,
68 - "timeoutMs": 600000,
69 - "maxWatchDirs": 10000,
70 - "notify": "errors",
71 - "commentPrefixes": {
72 - "foo": ["COMMENT"],
73 - "lua": ["--"]
74 - }
75 - }
173 + "llmiterate": {
174 + "enabled": true,
175 + "include": ["src/**/*.{ts,tsx,rs,java,md}", "docs/**/*.md"],
176 + "exclude": ["**/target/**", "**/dist/**"],
177 + "debounceMs": 3000,
178 + "maxFileBytes": 1000000,
179 + "timeoutMs": 600000,
180 + "maxWatchDirs": 10000,
181 + "notify": "errors",
182 + "commentPrefixes": {
183 + "foo": ["COMMENT"],
184 + "lua": ["--"]
79 -## Behavior
81 -llmiterate does not autostart.
82 -`/llmiterate` or `/llmiterate on` starts it for the exact real cwd.
83 -It loads global Pi settings, then `<scope>/.pi/settings.json`; there is no
84 -upward project-root search.
86 -Start sequence:
88 -1. resolve cwd
89 -2. load config and state
90 -3. acquire singleton lock for the scope hash
91 -4. start watcher
92 -5. run initial scan
93 -6. queue matching markers
190 +## Internals
95 192 Only one watcher may own an exact real cwd at a time.
96 193 Another Pi session in the same cwd enters standby and reports the lock owner.
110 207 It queues prompts.
111 208 A background Pi RPC worker performs edits with normal Pi tools.
113 -Worker args:
115 -```text
116 ---mode rpc
117 ---offline
118 ---session-dir <state>/sessions
119 ---append-system-prompt <llmiterate worker rules>
120 ---model <optional>
121 ---thinking <optional>
122 -```
124 -Worker env:
126 -```text
127 -LLMITERATE_WORKER=1
128 -```
130 -`LLMITERATE_WORKER=1` prevents recursive llmiterate watchers while keeping other
131 -extensions available.
133 210 State file:
135 212 ```text
166 243 - `/llmiterate log`:
167 244 latest worker JSONL transcript rendered as markdown at
168 245 `<state>/logs/latest.md`
170 -## Marker syntax
172 -One marker only:
174 -```text
175 -llmiterate:
176 -```
178 -Marker must appear after a known comment prefix.
179 -Raw markers never run.
181 -```java
182 -void main(final String[] a) {
183 - // llmiterate: implement argument validation
184 - if (a.length == 0) {
185 - // llmiterate: print usage and exit non-zero
186 - }
188 -```
190 -```py
191 -def parse(src):
192 - # llmiterate: implement parser fast path
193 -```
195 -```sql
196 --- llmiterate: add index for lookup query
197 -```
199 -Rules:
201 -- raw `llmiterate:` is ignored
202 -- legacy `LLM` / `PROMPT` is ignored
203 -- consecutive marker lines are grouped
204 -- empty marker lines are ignored
205 -- `!llmiterate` in a comment disables the whole file
207 -```md
208 -<!-- !llmiterate -->
209 -```
211 -## Comment prefixes
213 -Prefixes are extension-scoped.
214 -Built-ins include:
216 -```text
217 -.c/.cc/.cpp/.cs/.cts/.go/.h/.hpp/.java/.js/.jsx/.kt/.kts/.mts/.php/.scala/.swift/.ts/.tsx // /// /* /**
218 -.rs // /// //! /* /**
219 -.css /* /**
220 -.scss/.less // /* /**
221 -.py/.sh/.bash/.zsh/.fish/.rb/.pl/.pm/.r/.toml/.yaml/.yml/.dockerfile/.ex/.exs #
222 -.md/.mdx/.html/.htm/.xml <!-- -->
223 -.sql/.lua/.hs --
224 -.lisp/.el/.clj/.scm ; ;; ;;;
225 -.tex % %%
226 -.erl %
227 -.f/.f90 !
228 -```
230 -Unknown extensions do not run markers.
231 -Markdown only accepts HTML comments, so headings or bullets containing
232 -`llmiterate:` are inert.
234 -Config `commentPrefixes` appends by extension:
236 -```json
238 - "llmiterate": {
239 - "commentPrefixes": {
240 - "foo": ["COMMENT"],
241 - "lua": ["--"]
242 - }
243 - }
245 -```
247 -## Replacement behavior
249 -For each marker block, the worker receives a prompt containing:
251 -- source location:
252 - `@file:startLine`
253 -- marker text
254 -- marker span to replace
255 -- instruction to work in/around the file
256 -- instruction to remove the marker unless impossible
258 -Before a job starts, llmiterate rechecks that the marker still exists at the
259 -same line with the same prompt hash.
260 -If it changed, the job is failed as stale and skipped.
262 -After the worker finishes, llmiterate rechecks the file.
263 -If the same marker is still present at the same line with the same prompt hash,
264 -the job is marked failed.
265 -Otherwise that job is marked done.