@miragon/pulse-engine-core 0.0.0-bootstrap.0 → 0.0.0-stage
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 +2 -97
- package/package.json +4 -13
package/README.md
CHANGED
|
@@ -1,98 +1,3 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Temporary Holding Version
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](https://github.com/Miragon/pulse/actions/workflows/ci.yml)
|
|
5
|
-
[](https://miragon.github.io/pulse/)
|
|
6
|
-
|
|
7
|
-
The workflow domain of the Camunda 7 REST API family (Operaton, CIB seven, Camunda 7): where a
|
|
8
|
-
process instance waits and why, how an engine is doing, and what retry and advance would send,
|
|
9
|
-
and the pure engine REST rules every caller of this API needs (dates, filters, sorting, variable
|
|
10
|
-
writes, incident recovery). It runs on an engine port you implement and returns data.
|
|
11
|
-
|
|
12
|
-
## Who uses it
|
|
13
|
-
|
|
14
|
-
[pulse-cli](https://www.npmjs.com/package/@miragon/pulse-cli) bundles it: `inspect`, `status`,
|
|
15
|
-
`wait`, `advance` and `retry` run on it and word its results as command lines and CLI errors.
|
|
16
|
-
[@miragon/pulse-engine-connector](https://www.npmjs.com/package/@miragon/pulse-engine-connector)
|
|
17
|
-
runs inspect and status on it over its client, as the MCP tools `engine_inspect_process_instance`
|
|
18
|
-
and `engine_status`.
|
|
19
|
-
Pulse for VS Code bundles it in its C7 adapter: an instance's panel reads the instance through
|
|
20
|
-
`loadInstance` and the root cause of an incident through `rootCause` and `rootCauseLine`.
|
|
21
|
-
It is the shared domain of every Pulse interface to this API family, so an MCP tool and a CLI
|
|
22
|
-
command answer the same question by the same rules.
|
|
23
|
-
|
|
24
|
-
One port per API family: the vendors differ in runtime configuration, never in this package.
|
|
25
|
-
|
|
26
|
-
## What it is not
|
|
27
|
-
|
|
28
|
-
No HTTP, no authentication and no runtime dependency: it imports only its own modules. It names
|
|
29
|
-
no command, flag or tool: next steps are structured (`{ action: "retry", processInstanceId }`),
|
|
30
|
-
errors are `WorkflowError`s with a `reason` (`{ kind: "selection-ambiguous", candidates, more }`),
|
|
31
|
-
and the caller words both. The English texts that describe the engine's state are the package's
|
|
32
|
-
and shared by every caller: the finding messages of the status triage, its truncation notes and
|
|
33
|
-
the summaries of planned writes (`execute job j1`).
|
|
34
|
-
|
|
35
|
-
## Install
|
|
36
|
-
|
|
37
|
-
```sh
|
|
38
|
-
npm install @miragon/pulse-engine-core
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
## The API in brief
|
|
42
|
-
|
|
43
|
-
- **Port:** `createEnginePort(transport)` turns your `EngineTransport` (send an operation by its
|
|
44
|
-
REST operation id, read an answer as JSON or text, read an engine failure) into the
|
|
45
|
-
`EnginePort` the workflows run on, with the shared read rules: pages of 500, a missing resource
|
|
46
|
-
as undefined, blank texts as undefined. A missing resource is an engine 404 whose exception type
|
|
47
|
-
is neither `NotFoundException` (no such endpoint, a wrong REST root) nor `QueryParamException`,
|
|
48
|
-
so your `failure` reading must carry the engine's `engineType`: without it a missing instance
|
|
49
|
-
fails instead of reading as missing.
|
|
50
|
-
- **Inspect:** `inspectInstance(port, selection, options)` selects an instance by id, by business
|
|
51
|
-
key or by key with `latest`, and loads its view: wait states with their ids, root-cause
|
|
52
|
-
incidents, called instances, optionally variables, the history timeline and stacktraces (cut
|
|
53
|
-
after `MAX_STACKTRACE_LINES` lines).
|
|
54
|
-
- **Status:** `readStatus({ port, now }, options)` triages one engine: findings with severity, the
|
|
55
|
-
overall status, definitions, incident groups with their root cause, topics, jobs and batches,
|
|
56
|
-
every cut named in `truncated`.
|
|
57
|
-
- **Plans:** the pure parts of retry (`planRetry`, `retriesWrite`), advance (`chooseWait`,
|
|
58
|
-
`advanceSteps`) and wait (`parseCondition`, `decide`, `poll`).
|
|
59
|
-
- **Engine REST rules:** the one home of what the engine expects other than what a caller
|
|
60
|
-
naturally sends: dates (`toEngineDate`, `engineDateInput` in a `DateInputReading`:
|
|
61
|
-
`OFFSET_REQUIRED` refuses a time without an offset, `UTC_WITHOUT_OFFSET` reads it as UTC;
|
|
62
|
-
`engineDateMillis`, `latestEngineDate`), true-only and `…Like` filters (`trueOnly`,
|
|
63
|
-
`complementaryFlags`, `engineLike`, `engineKeyList`, `engineInstanceSearch`), paired sorting
|
|
64
|
-
(`engineSorting`), variable writes and typing (`toEngineVariable(s)`, `autoTypedValue`),
|
|
65
|
-
incident recovery (`incidentRecovery`), the raw variable read flag (`RAW_VARIABLES`) and root
|
|
66
|
-
causes (`rootCause`, and `rootCauseLine`, the line a viewer opens the text at).
|
|
67
|
-
|
|
68
|
-
```ts
|
|
69
|
-
import { createEnginePort, type EngineTransport, inspectInstance } from "@miragon/pulse-engine-core"
|
|
70
|
-
|
|
71
|
-
// Your client's answer of one request, read right after it arrived.
|
|
72
|
-
type Answer = { readonly body?: unknown; readonly text?: string }
|
|
73
|
-
|
|
74
|
-
const transport: EngineTransport<Answer> = {
|
|
75
|
-
send: (operationId, input) => yourClient.send(operationId, input),
|
|
76
|
-
json: (answer) => answer.body,
|
|
77
|
-
text: (answer) => answer.text,
|
|
78
|
-
failure: (error) =>
|
|
79
|
-
error instanceof YourHttpError
|
|
80
|
-
? { status: error.status, engineType: error.type, engineMessage: error.message }
|
|
81
|
-
: undefined,
|
|
82
|
-
}
|
|
83
|
-
const port = createEnginePort(transport)
|
|
84
|
-
const view = await inspectInstance(
|
|
85
|
-
port,
|
|
86
|
-
{ businessKey: "B-1", latest: true },
|
|
87
|
-
{ variables: true, history: false, stacktrace: false },
|
|
88
|
-
)
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
## Testing helpers
|
|
92
|
-
|
|
93
|
-
`@miragon/pulse-engine-core/testing` exports the verified workflow fixture, the status fixture,
|
|
94
|
-
wait states of every kind, `fakePort` (a recording port over canned answers that refuses any
|
|
95
|
-
operation without a route) and `fakeClock`. It also exports the rules behind the entry's
|
|
96
|
-
functions that tests reach directly, and `INSPECT_OPERATIONS` and `STATUS_OPERATIONS`, the
|
|
97
|
-
operations each composite sends: a port that maps operations one by one holds its table equal to
|
|
98
|
-
them in a test.
|
|
3
|
+
This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
|
package/package.json
CHANGED
|
@@ -1,15 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@miragon/pulse-engine-core",
|
|
3
|
-
"version": "0.0.0-
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
7
|
-
"type": "git",
|
|
8
|
-
"url": "git+https://github.com/Miragon/pulse.git",
|
|
9
|
-
"directory": "packages/connectors/engine/engine-core"
|
|
10
|
-
},
|
|
11
|
-
"publishConfig": {
|
|
12
|
-
"access": "public",
|
|
13
|
-
"tag": "bootstrap"
|
|
14
|
-
}
|
|
15
|
-
}
|
|
3
|
+
"version": "0.0.0-stage",
|
|
4
|
+
"stub": true,
|
|
5
|
+
"description": "Temporary package placeholder for staged publishing"
|
|
6
|
+
}
|