@orkestrel/scaffold 0.0.119 → 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.
- package/dist/bin/main.js +19 -19
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
- package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +52 -51
- package/dist/host/claude/rules/tests.md +2 -2
- package/dist/host/claude/rules/typescript.md +2 -3
- package/dist/host/guides/abort.md +0 -4
- package/dist/host/guides/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/contract.md +23 -44
- package/dist/host/guides/csv.md +86 -93
- package/dist/host/guides/database.md +0 -4
- package/dist/host/guides/emitter.md +0 -2
- package/dist/host/guides/form.md +26 -47
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +148 -144
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/sqlite.md +0 -4
- package/dist/host/guides/sse.md +6 -10
- package/dist/host/guides/table.md +481 -493
- package/dist/host/guides/template.md +0 -4
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/toolbox.md +0 -10
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +64 -909
- package/dist/src/core/index.cjs +128 -181
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +213 -213
- package/dist/src/core/index.d.ts +213 -213
- package/dist/src/core/index.js +117 -170
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +35 -34
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +62 -58
- package/dist/src/server/index.d.ts +62 -58
- package/dist/src/server/index.js +36 -35
- package/dist/src/server/index.js.map +1 -1
- package/package.json +13 -13
|
@@ -191,14 +191,10 @@ The **browser** backends ship in [`src/browser`](../src/browser), published thro
|
|
|
191
191
|
|
|
192
192
|
The browser backends also publish supporting members through `@orkestrel/workflow/browser`: the `POST_TASK_PRIORITY` map `BrowserScheduler` reads to translate a portable `SchedulerPriority` into a `scheduler.postTask` priority level, and the `IdleInterface` shape of the feature-detected `requestIdleCallback` / `cancelIdleCallback` pair `IdleScheduler` narrows to (or resolves to `undefined`, falling back to a macrotask).
|
|
193
193
|
|
|
194
|
-
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 `\|`.
|
|
195
|
-
|
|
196
194
|
| Name | Kind | Signature | Summary |
|
|
197
195
|
| --------------- | --------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
198
196
|
| `IdleInterface` | interface | `{ request, cancel }` | Declares the narrowed `requestIdleCallback` / `cancelIdleCallback` pair feature-detected off `globalThis`. |
|
|
199
197
|
|
|
200
|
-
A `Shape` cell holds the constant's declared type.
|
|
201
|
-
|
|
202
198
|
| Name | Kind | Signature | Summary |
|
|
203
199
|
| -------------------- | ----- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
204
200
|
| `POST_TASK_PRIORITY` | const | `Readonly<Record<SchedulerPriority, string>>` | Maps each portable `SchedulerPriority` to the browser-native `postTask` priority — `user` to `'user-blocking'`, `normal` to `'user-visible'`, and `background` to `'background'`. |
|
|
@@ -242,7 +238,9 @@ Centralized, exhaustively unit-tested helpers and guards. The status derivations
|
|
|
242
238
|
Generic exact-JSON ownership comes directly from [`@orkestrel/contract`](contract.md):
|
|
243
239
|
consumers import its `JSONRecord`, `cloneJSONValue`, and `cloneJSONRecord` from their
|
|
244
240
|
originating package. Workflow does not re-export them. Its domain cloners below add
|
|
245
|
-
workflow-specific validation and translate ownership failures into `WorkflowError`.
|
|
241
|
+
workflow-specific validation and translate ownership failures into `WorkflowError`. The
|
|
242
|
+
`success` and `failure` constructors that box a `Result`, and the `errorToMessage` function
|
|
243
|
+
that renders a thrown value as a failure message, also come from `@orkestrel/contract`.
|
|
246
244
|
|
|
247
245
|
| Name | Kind | Signature | Summary |
|
|
248
246
|
| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -267,9 +265,6 @@ workflow-specific validation and translate ownership failures into `WorkflowErro
|
|
|
267
265
|
| `isTaskActivity` | function | `(value: unknown) => value is TaskActivity` | Tests whether an unknown value is valid persisted task activity. |
|
|
268
266
|
| `captureWorkflowOptions` | function | `(options?: WorkflowOptions) => WorkflowOptions` | Captures every top-level `WorkflowOptions` value exactly once into an owned plain bag. |
|
|
269
267
|
| `createHostSchedule` | function | `(start: HostScheduleFunction, signal?: AbortSignal) => Promise<void>` | Schedules one cancellable host operation behind an owned settlement signal. |
|
|
270
|
-
| `success` | function | `<T>(value: T) => Success<T>` | Boxes a value as a `Success` — the graceful outcome half of a `Result`. |
|
|
271
|
-
| `failure` | function | `<E>(error: E) => Failure<E>` | Boxes an error as a `Failure` — the graceful outcome half of a `Result`. |
|
|
272
|
-
| `errorToMessage` | function | `(error: unknown) => string` | Normalizes an unknown thrown value to a non-empty persistence-safe message. |
|
|
273
268
|
| `findFailure` | function | `(results: readonly TaskResult[]) => TaskResult \| undefined` | Finds the first `TaskResult` in a positional list whose boxed outcome is a `Failure` — the pure scan shared by a phase's and a workflow's derived-`failed` `fail`-event lookup. |
|
|
274
269
|
| `buildWorkflowContext` | function | `(node: WorkflowContext) => WorkflowContext` | Builds a `WorkflowContext` — the identity every level inherits — from a node's `id` / `name` / optional `description`. |
|
|
275
270
|
| `buildPhaseContext` | function | `(workflow: WorkflowContext, node: WorkflowContext) => PhaseContext` | Builds a `PhaseContext` — a phase's own identity plus a back-reference to its workflow — from the parent `WorkflowContext` and the phase node's identity. |
|
|
@@ -302,7 +297,6 @@ The exact snapshot boundary is also available as composable public leaves:
|
|
|
302
297
|
import {
|
|
303
298
|
cloneWorkflowSnapshot,
|
|
304
299
|
createWorkflow,
|
|
305
|
-
errorToMessage,
|
|
306
300
|
hasWorkflowHandlers,
|
|
307
301
|
isLifecycleStatus,
|
|
308
302
|
isOwnedWorkflowSnapshot,
|
|
@@ -341,7 +335,6 @@ if (phase !== undefined && task !== undefined) {
|
|
|
341
335
|
matchesDescription(snapshot.description, workflow.description)
|
|
342
336
|
hasWorkflowHandlers(snapshot, functions)
|
|
343
337
|
scanSnapshotContext({ ...snapshot, bail: 'invalid' })
|
|
344
|
-
errorToMessage(new Error('provider failed'))
|
|
345
338
|
recoverWorkflowSnapshot(snapshot)
|
|
346
339
|
```
|
|
347
340
|
|
|
@@ -365,20 +358,16 @@ resolveTaskSilence(0, 30_000) // undefined: the task explicitly disables inherit
|
|
|
365
358
|
|
|
366
359
|
`createWorkflowContract` derives its lockstep JSON Schema, guard, parser, and generator from these shape values. They agree with the hand-written definition interfaces (the source of truth); a round-trip parity test (`generate → is → parse`) guards against drift.
|
|
367
360
|
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
|
371
|
-
|
|
|
372
|
-
| `
|
|
373
|
-
| `
|
|
374
|
-
| `
|
|
375
|
-
| `taskUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of a `TaskUpdate` — a partial edit to a `pending` task's `name` / `description`, both optional. |
|
|
376
|
-
| `phaseUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseUpdate` — a partial edit to a `pending` phase's `name` / `description` / `concurrency` / `bail`, all optional. |
|
|
361
|
+
| Name | Kind | Signature | Summary |
|
|
362
|
+
| --------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
363
|
+
| `taskDefinitionShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>` | Describes the shape of a `TaskDefinition` — identity plus an optional `behavior` behavior reference (a plain registry-key string, min length 1). `description` is optional prose. |
|
|
364
|
+
| `phaseShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseDefinition` — identity, its ordered `taskDefinitionShape` tasks, and an optional positive-integer `concurrency` throttle (max tasks in flight; omitted ⇒ unbounded). |
|
|
365
|
+
| `workflowShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; phases: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `WorkflowDefinition` — the contract root: identity, its ordered `phaseShape` phases, and the optional `bail` boolean failure policy (the literal pair `true`/`false`, the runtime mirror of the boolean toggle; omitted ⇒ the graceful default). |
|
|
366
|
+
| `taskUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of a `TaskUpdate` — a partial edit to a `pending` task's `name` / `description`, both optional. |
|
|
367
|
+
| `phaseUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseUpdate` — a partial edit to a `pending` phase's `name` / `description` / `concurrency` / `bail`, all optional. |
|
|
377
368
|
|
|
378
369
|
### Constants
|
|
379
370
|
|
|
380
|
-
A `Shape` cell holds the constant's declared type.
|
|
381
|
-
|
|
382
371
|
| Name | Kind | Signature | Summary |
|
|
383
372
|
| --------------------------- | ----- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
384
373
|
| `DEFAULT_BAIL` | const | `false` | Names the default `WorkflowDefinition.bail`, `false` — the graceful policy that records a leaf failure and finishes every phase. |
|
|
@@ -392,8 +381,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
392
381
|
|
|
393
382
|
### Types
|
|
394
383
|
|
|
395
|
-
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 `\|`.
|
|
396
|
-
|
|
397
384
|
| Name | Kind | Signature | Summary |
|
|
398
385
|
| ------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
399
386
|
| `TaskDefinition` | interface | `{ id, name, description?, behavior?, retries?, timeout? }` | Represents the serializable definition of one task — its identity, an optional reference to the behavior it runs, and its optional per-task `retries` and `timeout` overrides. |
|
|
@@ -406,8 +393,8 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
406
393
|
| `PhaseInput` | type | `Partial<PhaseContext>` | Represents the minimal data to create a phase context — a partial `PhaseContext`. |
|
|
407
394
|
| `TaskInput` | interface | `{ metadata? }` | Represents the minimal data to create a task context — a partial `TaskContext` plus the open `metadata` bag the task stores and snapshots without interpreting it. |
|
|
408
395
|
| `TaskProgress` | interface | `{ progress, total?, message? }` | Represents the aggregate progress most recently reported by a running task. |
|
|
409
|
-
| `TaskClaim` | interface | `{ id, name, started }` | Represents one identified thing a running task claims active, with the moment the claim began — the shape `
|
|
410
|
-
| `
|
|
396
|
+
| `TaskClaim` | interface | `{ id, name, started }` | Represents one identified thing a running task claims active, with the moment the claim began — the shape `TaskActivityOperation` and `TaskConstraint` share. |
|
|
397
|
+
| `TaskActivityOperation` | interface | `{}` | Represents one operation claimed active when a running task's complete frame was accepted. |
|
|
411
398
|
| `TaskConstraint` | interface | `{}` | Represents one constraint claimed active when a running task's complete frame was accepted. |
|
|
412
399
|
| `TaskActivityInput` | interface | `{ note?, progress?, operations?, constraints? }` | Represents one complete replacement of a running task's observable activity, an omitted collection meaning an empty one. |
|
|
413
400
|
| `TaskActivity` | interface | `{ note?, progress?, operations, constraints, updated }` | Represents the bounded, JSON-serializable activity most recently accepted from a task reporter. |
|
|
@@ -1565,7 +1552,7 @@ A successful run fires `start` → `unit`/`settle` per unit → `finish`. A fail
|
|
|
1565
1552
|
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — status/lineage/snapshot helpers, bounded silence inheritance, `createHostSchedule` setup/cancellation race arbitration with exact falsy failures, hostile caller signal methods, and throwing cancellation closures after caller abort or host failure, plus the snapshot-decode leaves: remaining-budget recovery, established strict halt boundaries, exhausted recovery failures, monotonic stamps, exact-restore separation, and hostile inputs.
|
|
1566
1553
|
- [`tests/src/core/cloners.test.ts`](../tests/src/core/cloners.test.ts) — immutable activity cloning, hostile/revoked proxy containment, one-read getters, no alias retention, stamp-vs-restore `updated` handling, and exact wrong-storage-key `RESTORE` evidence.
|
|
1567
1554
|
- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — total activity, task-failure, task-result, and owned-snapshot guards over valid, malformed, cyclic, throwing-proxy/getter/ownKeys, and revoked inputs.
|
|
1568
|
-
- [`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts) — the shape descriptors: the `
|
|
1555
|
+
- [`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts) — the shape descriptors: the `taskDefinitionShape` / `phaseShape` / `workflowShape` mirroring the hand-written definition interfaces, the per-field `description`s riding the `behavior` string + key fields (Rank 1), `describedLiteral`.
|
|
1569
1556
|
- [`tests/src/core/tasks/Task.test.ts`](../tests/src/core/tasks/Task.test.ts) — lifecycle plus whole-frame activity, validation/immutability, pulse, repeatable silence rearming, task signal, terminal cleanup, and cooperative pause.
|
|
1570
1557
|
- [`tests/src/core/phases/Phase.test.ts`](../tests/src/core/phases/Phase.test.ts) — the derived middle tier: child-transition cascade, `skip` / `stop` override, results, snapshot/restore, and isolated lifecycle emission including idempotent pause/resume.
|
|
1571
1558
|
- [`tests/src/core/Workflow.test.ts`](../tests/src/core/Workflow.test.ts) — the derived root: bail-aware cascade, result tree, override, snapshot/restore, teardown, and isolated lifecycle emission including idempotent pause/resume.
|
|
@@ -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
|
-
| `
|
|
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
|
-
| `
|
|
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
|
-
| `
|
|
96
|
-
| `clampRange` | function | `(text: string, range: Range) => Range` | Clamps both
|
|
97
|
-
| `offsetAt` | function | `(text: string,
|
|
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
|
-
|
|
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
|
-
|
|
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`, `
|
|
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
|
|
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,
|
|
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`
|
|
349
|
-
passes it through as pattern source instead. `limit` caps
|
|
350
|
-
`replace`, counted across files in insertion order. A
|
|
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
|
|