@orkestrel/scaffold 0.0.120 → 0.0.121

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.
Files changed (40) hide show
  1. package/dist/bin/main.js +5 -5
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/claude/agents/orkestrel.md +26 -26
  4. package/dist/host/guides/agent.md +5 -5
  5. package/dist/host/guides/brief.md +7 -15
  6. package/dist/host/guides/browser.md +1 -1
  7. package/dist/host/guides/capture.md +2 -2
  8. package/dist/host/guides/console.md +4 -30
  9. package/dist/host/guides/guide.md +0 -1
  10. package/dist/host/guides/interpret.md +165 -182
  11. package/dist/host/guides/lsp.md +26 -51
  12. package/dist/host/guides/mcp.md +220 -276
  13. package/dist/host/guides/middleware.md +14 -22
  14. package/dist/host/guides/ollama.md +1 -3
  15. package/dist/host/guides/probe.md +71 -80
  16. package/dist/host/guides/program.md +26 -35
  17. package/dist/host/guides/qualifier.md +0 -6
  18. package/dist/host/guides/queue.md +0 -4
  19. package/dist/host/guides/rater.md +6 -12
  20. package/dist/host/guides/relation.md +0 -2
  21. package/dist/host/guides/scaffold.md +12 -8
  22. package/dist/host/guides/sea.md +47 -51
  23. package/dist/host/guides/server.md +15 -19
  24. package/dist/host/guides/terminal.md +0 -26
  25. package/dist/host/guides/toolbox.md +0 -10
  26. package/dist/host/guides/worker.md +57 -57
  27. package/dist/host/guides/workflow.md +13 -26
  28. package/dist/host/guides/workspace.md +15 -21
  29. package/dist/host/manifest.json +28 -448
  30. package/dist/src/core/index.cjs +7 -45
  31. package/dist/src/core/index.cjs.map +1 -1
  32. package/dist/src/core/index.js +7 -45
  33. package/dist/src/core/index.js.map +1 -1
  34. package/dist/src/server/index.cjs +10 -9
  35. package/dist/src/server/index.cjs.map +1 -1
  36. package/dist/src/server/index.d.cts +12 -8
  37. package/dist/src/server/index.d.ts +12 -8
  38. package/dist/src/server/index.js +10 -9
  39. package/dist/src/server/index.js.map +1 -1
  40. package/package.json +5 -5
@@ -33,8 +33,6 @@ documented under [`## Methods`](#methods), and its readonly data members stay he
33
33
  `emitter`, and `count` on `WorkspaceInterface`, `count` and `active` on
34
34
  `WorkspaceManagerInterface`, and none on `WorkspaceStoreInterface`.
35
35
 
36
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
37
-
38
36
  | Name | Kind | Signature | Summary |
39
37
  | --------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40
38
  | `BinaryMIME` | type | `'image/png' \| 'image/jpeg' \| 'image/gif' \| 'image/webp'` | Names the MIME labels a binary `FileContent` arm supports. |
@@ -44,7 +42,7 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
44
42
  | `FileState` | type | `'created' \| 'modified'` | Names the edit state of an immutable file value: `created` for the first write to a path and `modified` for every later edit of that path. |
45
43
  | `FileInput` | interface | `{ path, content, state? }` | Carries the caller-supplied values used to create an immutable file. The byte size and the line count are derived rather than supplied. |
46
44
  | `FileInterface` | interface | `{ path, content, state, size, lines }` | Represents an immutable path-addressed file with derived byte and line counts. |
47
- | `Position` | interface | `{ line, column }` | Locates a 1-based caret inside text. |
45
+ | `Caret` | interface | `{ line, column }` | Locates a 1-based caret inside text. |
48
46
  | `Range` | interface | `{ start, end }` | Represents a half-open text span whose start is inclusive and end is exclusive. |
49
47
  | `ReadResult` | interface | `{ content, range }` | Carries the content and clamped span returned by a ranged read. |
50
48
  | `SearchOptions` | interface | `{ regex?, sensitive?, limit? }` | Configures search and replacement behavior. |
@@ -62,8 +60,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
62
60
 
63
61
  ### Constants
64
62
 
65
- A `Shape` cell holds the constant's declared type.
66
-
67
63
  | Name | Kind | Signature | Summary |
68
64
  | --------------------- | ----- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
69
65
  | `EXTENSION_LANGUAGES` | const | `Readonly<Record<string, string>>` | Maps file extensions to language tags for text content. The table is frozen, and an extension it does not list falls back to `text` in `inferLanguage`. |
@@ -86,27 +82,24 @@ on its own, and the classes compose them rather than hiding them.
86
82
  | Name | Kind | Signature | Summary |
87
83
  | -------------------- | -------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
88
84
  | `inferLanguage` | function | `(path: string) => string` | Infers a language tag from the final file extension. |
89
- | `isText` | function | `(content: FileContent) => content is TextContent` | Determines whether content is the text arm. |
85
+ | `isTextContent` | function | `(content: FileContent) => content is TextContent` | Determines whether content is the text arm. |
90
86
  | `isBinary` | function | `(content: FileContent) => content is BinaryContent` | Determines whether content is the binary arm. |
91
87
  | `computeSize` | function | `(content: FileContent) => number` | Computes the byte size of file content. |
92
88
  | `countLines` | function | `(content: FileContent) => number` | Counts the lines in file content. |
93
89
  | `computeDecodedSize` | function | `(base64: string) => number` | Computes the decoded byte length of a base64 string, arithmetically rather than by decoding it. |
94
90
  | `isValidRange` | function | `(range: Range) => boolean` | Determines whether a 1-based range is structurally valid. |
95
- | `clampPosition` | function | `(text: string, position: Position) => Position` | Clamps a position to text bounds. |
96
- | `clampRange` | function | `(text: string, range: Range) => Range` | Clamps both positions in a range to text bounds. |
97
- | `offsetAt` | function | `(text: string, position: Position) => number` | Converts a 1-based position to a zero-based string offset. |
91
+ | `clampCaret` | function | `(text: string, caret: Caret) => Caret` | Clamps a caret to text bounds. |
92
+ | `clampRange` | function | `(text: string, range: Range) => Range` | Clamps both carets in a range to text bounds. |
93
+ | `offsetAt` | function | `(text: string, caret: Caret) => number` | Converts a 1-based caret to a zero-based string offset. |
98
94
  | `sliceRange` | function | `(text: string, range: Range) => string` | Slices a clamped half-open text range. |
99
95
  | `spliceRange` | function | `(text: string, range: Range, replacement: string) => string` | Replaces a clamped half-open text range. |
100
96
  | `rangeOf` | function | `(fromLine: number, fromColumn: number, toLine: number, toColumn: number) => Range` | Assembles a nested range from four 1-based coordinates. |
101
- | `escapeRegExp` | function | `(value: string) => string` | Escapes regular-expression metacharacters for literal matching. |
102
97
 
103
98
  ### Validators
104
99
 
105
100
  The total guards, from [`validators.ts`](../src/core/validators.ts). Each narrows an `unknown`
106
101
  value arriving from outside the process without throwing on a hostile property access.
107
102
 
108
- In a guard table a `Shape` cell holds the type the guard narrows to.
109
-
110
103
  | Name | Kind | Signature | Summary |
111
104
  | --------------------- | -------- | ------------------------------------------------ | ----------------------------------------------------- |
112
105
  | `isFile` | function | `(value: unknown) => value is FileInterface` | Narrows an unknown value to an immutable file record. |
@@ -244,7 +237,7 @@ import {
244
237
  createTextContent,
245
238
  inferLanguage,
246
239
  isBinary,
247
- isText,
240
+ isTextContent,
248
241
  } from '@orkestrel/workspace'
249
242
 
250
243
  const note = createFile({
@@ -255,7 +248,7 @@ const note = createFile({
255
248
  note.size // 12 — UTF-8 bytes, through computeSize
256
249
  note.lines // 2 — through countLines
257
250
  note.state // 'created'
258
- isText(note.content) // true
251
+ isTextContent(note.content) // true
259
252
 
260
253
  const icon = createFile({ path: 'icon.png', content: createBinaryContent('AAAA', 'image/png') })
261
254
  isBinary(icon.content) // true
@@ -305,11 +298,11 @@ path with `Cannot splice a range of a binary file: <path>` under `MODALITY`. A s
305
298
  impossible range — inverted, or with a coordinate below one — throws `RANGE`. A range that is merely too
306
299
  large is not an error: both endpoints clamp to the text's bounds, so `rangeOf(1, 2, 9, 9)` over
307
300
  `'abc'` addresses everything from the second column onward. The pure functions behind that
308
- behavior are exported and usable on their own: `isValidRange`, `clampPosition`, `clampRange`,
301
+ behavior are exported and usable on their own: `isValidRange`, `clampCaret`, `clampRange`,
309
302
  `offsetAt`, `sliceRange`, and `spliceRange`.
310
303
 
311
304
  Ranges are half-open and 1-based. `rangeOf(1, 1, 1, 6)` covers the first five columns of line one,
312
- which is the convention every editor position in this package follows.
305
+ which is the convention every caret in this package follows.
313
306
 
314
307
  ## Reading and searching
315
308
 
@@ -317,7 +310,7 @@ Reads are shaped by what the caller asked for, and binary content is quietly abs
317
310
  that promise text:
318
311
 
319
312
  ```ts
320
- import { createWorkspace, escapeRegExp, rangeOf } from '@orkestrel/workspace'
313
+ import { createWorkspace, rangeOf } from '@orkestrel/workspace'
321
314
 
322
315
  const workspace = createWorkspace()
323
316
  workspace.write({ 'a.ts': 'const x = 1\nconst y = 2', 'b.ts': 'const z = 3' })
@@ -335,9 +328,9 @@ workspace.has(['missing.ts', 'b.ts']) // false — a batch answers true only whe
335
328
 
336
329
  workspace.search('const') // three matches, a.ts before b.ts, line order within each
337
330
  workspace.search('[a-z]\\d', { regex: true }) // pattern source instead of literal text
331
+ workspace.search('const.') // [] — a literal query reads '.' as a dot, not as any character
338
332
  workspace.search('CONST', { sensitive: false, limit: 2 })
339
333
  workspace.replace('const', 'let') // { occurrences: 3, files: 2 }
340
- escapeRegExp('a.b') // 'a\\.b' — what a literal search does for you
341
334
  ```
342
335
 
343
336
  A plain read of a binary path returns `undefined`, exactly as an absent path does; a batch read
@@ -345,9 +338,10 @@ omits both. A ranged read of binary content is the one that throws `MODALITY`, b
345
338
  named coordinates that cannot exist. Search and replace skip binary content entirely, so base64
346
339
  that happens to spell a query is never a hit.
347
340
 
348
- A query is literal by default — `escapeRegExp` neutralizes its metacharacters — and `regex: true`
349
- passes it through as pattern source instead. `limit` caps hits for `search` and replacements for
350
- `replace`, counted across files in insertion order. A pattern that will not compile throws
341
+ A query is literal by default — the `escapeRegExp` function from `@orkestrel/contract` neutralizes
342
+ its metacharacters — and `regex: true` passes it through as pattern source instead. `limit` caps
343
+ hits for `search` and replacements for `replace`, counted across files in insertion order. A
344
+ pattern that will not compile throws
351
345
  `PATTERN` rather than silently matching nothing. A zero-width pattern such as `a*` terminates: the
352
346
  scan advances past an empty match instead of re-matching the same column.
353
347