@intellectual-frontiers/integrations 0.0.0-stage → 0.1.1
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/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/governance/exchange.d.ts +224 -0
- package/dist/governance/exchange.js +86 -0
- package/dist/governance/ids.d.ts +61 -0
- package/dist/governance/ids.js +53 -0
- package/dist/governance/mod.d.ts +11 -0
- package/dist/governance/mod.js +12 -0
- package/dist/governance/observe.d.ts +172 -0
- package/dist/governance/observe.js +139 -0
- package/dist/logical/conformance.d.ts +44 -0
- package/dist/logical/conformance.js +108 -0
- package/dist/logical/constraints.d.ts +86 -0
- package/dist/logical/constraints.js +112 -0
- package/dist/logical/exchange.d.ts +98 -0
- package/dist/logical/exchange.js +135 -0
- package/dist/logical/ledger.d.ts +94 -0
- package/dist/logical/ledger.js +90 -0
- package/dist/logical/mapping.d.ts +64 -0
- package/dist/logical/mapping.js +99 -0
- package/dist/logical/mod.d.ts +18 -0
- package/dist/logical/mod.js +19 -0
- package/dist/logical/observe.d.ts +222 -0
- package/dist/logical/observe.js +156 -0
- package/dist/logical/plugin.d.ts +91 -0
- package/dist/logical/plugin.js +53 -0
- package/dist/logical/ports.d.ts +102 -0
- package/dist/logical/ports.js +31 -0
- package/dist/logical/registry.d.ts +72 -0
- package/dist/logical/registry.js +81 -0
- package/dist/logical/tree.d.ts +91 -0
- package/dist/logical/tree.js +114 -0
- package/dist/mod.d.ts +15 -0
- package/dist/mod.js +16 -0
- package/dist/physical/http/mod.d.ts +54 -0
- package/dist/physical/http/mod.js +114 -0
- package/dist/physical/transport/mod.d.ts +79 -0
- package/dist/physical/transport/mod.js +61 -0
- package/dist/surfaces/headless/mod.d.ts +46 -0
- package/dist/surfaces/headless/mod.js +258 -0
- package/package.json +67 -4
- package/src/governance/exchange.ts +220 -0
- package/src/governance/ids.ts +92 -0
- package/src/governance/mod.ts +12 -0
- package/src/governance/observe.ts +226 -0
- package/src/logical/conformance.ts +113 -0
- package/src/logical/constraints.ts +154 -0
- package/src/logical/exchange.ts +184 -0
- package/src/logical/ledger.ts +123 -0
- package/src/logical/mapping.ts +114 -0
- package/src/logical/mod.ts +19 -0
- package/src/logical/observe.ts +314 -0
- package/src/logical/plugin.ts +102 -0
- package/src/logical/ports.ts +89 -0
- package/src/logical/registry.ts +93 -0
- package/src/logical/tree.ts +153 -0
- package/src/mod.ts +16 -0
- package/src/physical/http/mod.ts +134 -0
- package/src/physical/transport/mod.ts +85 -0
- package/src/surfaces/headless/mod.ts +293 -0
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
// Spec: 0009-integrations-verbs FR-001, FR-002, FR-003, FR-004, FR-005
|
|
2
|
+
/**
|
|
3
|
+
* The headless verbs of Integrations (commons integrations 0009-integrations-verbs): `integrations observe|probe|check` for connectors and `integrations
|
|
4
|
+
* validate|translate|send|receive|explain` for exchange, as commands of Headless built from the typed cores, with their actions and reach policies declared, their
|
|
5
|
+
* outcome typed, and every outcome passed through the redaction of Headless over the values of the payload so that a payload never appears in what a verb says.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* Every effect is a port of `Deps`: the connectors and the way each reaches its system, the files, the transport of an agreement. A verb is a function of them,
|
|
9
|
+
* so that a test runs it over in-memory ports, and a program (the command line, a tool server, a REST interface) draws the same verbs.
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import { absurd, type Result } from "@intellectual-frontiers/core";
|
|
14
|
+
import { defineReach, problem, redactor, type Problem } from "@intellectual-frontiers/headless/governance";
|
|
15
|
+
import { branch, command, outcomeOf, redactOutcome, type Command, type Outcome } from "@intellectual-frontiers/headless/logical";
|
|
16
|
+
import { value } from "@intellectual-frontiers/terminal/args";
|
|
17
|
+
import {
|
|
18
|
+
hasErrors,
|
|
19
|
+
detect,
|
|
20
|
+
statusOf,
|
|
21
|
+
transition,
|
|
22
|
+
transactionsOf,
|
|
23
|
+
validate,
|
|
24
|
+
valuesOf,
|
|
25
|
+
type Clock,
|
|
26
|
+
type Connector,
|
|
27
|
+
type CredentialError,
|
|
28
|
+
type Acknowledgement,
|
|
29
|
+
type ExchangeState,
|
|
30
|
+
type Finding,
|
|
31
|
+
type FindingCode,
|
|
32
|
+
type PluginRegistry,
|
|
33
|
+
type ReadPort,
|
|
34
|
+
type Schema,
|
|
35
|
+
type Terminologies,
|
|
36
|
+
type Interchange,
|
|
37
|
+
} from "@intellectual-frontiers/integrations/logical";
|
|
38
|
+
import { parseAgreementId, parseConnectorId, type AgreementId, type ConnectorId, type ExchangeAgreement } from "@intellectual-frontiers/integrations/governance";
|
|
39
|
+
import type { Delivered, ExchangeTransport, TransportFailure } from "@intellectual-frontiers/integrations/transport";
|
|
40
|
+
|
|
41
|
+
/** Every effect the verbs need, as ports. */
|
|
42
|
+
export type Deps = {
|
|
43
|
+
readonly connectors: ReadonlyMap<ConnectorId, Connector>;
|
|
44
|
+
/** The read port of a connector's system, made from its credential reference at the edge. */
|
|
45
|
+
readonly readPort: (c: Connector) => Promise<Result<ReadPort, CredentialError>>;
|
|
46
|
+
readonly plugins: PluginRegistry;
|
|
47
|
+
readonly schemas: ReadonlyMap<string, Schema>;
|
|
48
|
+
readonly terminologies: Terminologies;
|
|
49
|
+
readonly agreements: ReadonlyMap<AgreementId, ExchangeAgreement>;
|
|
50
|
+
readonly readFile: (path: string) => Promise<Result<string, { readonly kind: "not-found" }>>;
|
|
51
|
+
readonly writeFile: (path: string, text: string) => Promise<Result<void, { readonly kind: "not-writable" }>>;
|
|
52
|
+
readonly transportOf: (a: ExchangeAgreement) => Promise<Result<ExchangeTransport, { readonly kind: "no-credential" }>>;
|
|
53
|
+
readonly clock: Clock;
|
|
54
|
+
};
|
|
55
|
+
|
|
56
|
+
const READ_ONLY = defineReach({ channels: ["local", "ssh", "mcp", "rest"], readOnly: true, idempotent: true });
|
|
57
|
+
const CHANGES = defineReach({ channels: ["local", "mcp", "rest"] });
|
|
58
|
+
|
|
59
|
+
const subject = (id: string): Problem => problem("fail", `there is no ${id}`, { code: "E010-UNKNOWN" });
|
|
60
|
+
|
|
61
|
+
/** One sentence for each code of a finding: what `explain` says. */
|
|
62
|
+
export const EXPLANATIONS: Readonly<Record<FindingCode, string>> = {
|
|
63
|
+
"syntax-error": "The text is not of the syntax: its envelope or structure is broken at the offset named. The text itself is never repeated.",
|
|
64
|
+
"unknown-path": "A path of the document is not one the schema defines.",
|
|
65
|
+
"cardinality-min": "A path occurs fewer times than the schema requires.",
|
|
66
|
+
"cardinality-max": "A path occurs more times than the schema allows.",
|
|
67
|
+
"value-pattern": "A value does not match the pattern the schema or profile gives its path.",
|
|
68
|
+
"value-fixed": "A value is not the one value the profile fixes for its path.",
|
|
69
|
+
"code-not-in-terminology": "A code is not in the terminology its path is bound to.",
|
|
70
|
+
"terminology-unavailable": "The terminology a path is bound to was not loaded, so the code could not be checked.",
|
|
71
|
+
"business-rule": "A rule of the agreement, written as a function of the document, found a fault.",
|
|
72
|
+
"unmapped-source-field": "A field of the source ends in no rule of the mapping: it is neither mapped, carried nor dropped by name.",
|
|
73
|
+
"lossy-mapping": "The mapping drops a field by name: what is dropped, and why, is said, and the mapping loses it.",
|
|
74
|
+
"mapping-target-conflict": "Two sources of a mapping are written to the same place of the target.",
|
|
75
|
+
};
|
|
76
|
+
|
|
77
|
+
const isFindingCode = (code: string): code is FindingCode => Object.hasOwn(EXPLANATIONS, code);
|
|
78
|
+
|
|
79
|
+
const byLevel = (fs: readonly Finding[]): Problem[] =>
|
|
80
|
+
fs.map((f) => problem(f.severity === "error" ? "fail" : "warn", f.message, { code: `E${f.level === "syntax" ? "100" : f.level === "schema" ? "110" : f.level === "profile" ? "120" : f.level === "terminology" ? "130" : "140"}-${f.code.toUpperCase().replaceAll("_", "-")}` }));
|
|
81
|
+
|
|
82
|
+
async function load(deps: Deps, path: string): Promise<Result<{ readonly tree: Interchange; readonly pluginId: string }, Outcome>> {
|
|
83
|
+
const text = await deps.readFile(path);
|
|
84
|
+
if (text.kind === "err") return { kind: "err", error: outcomeOf(null, { problems: [problem("fail", `${path} cannot be read`, { code: "E020-READ" })] }) };
|
|
85
|
+
const found = detect(deps.plugins, text.value);
|
|
86
|
+
if (found.kind === "err") return { kind: "err", error: outcomeOf(null, { problems: [problem("fail", `${path} is not of a syntax a plugin reads (${found.error.code} at ${found.error.offset})`, { code: "E100-SYNTAX-ERROR" })] }) };
|
|
87
|
+
return { kind: "ok", value: { tree: found.value.tree, pluginId: found.value.plugin.id } };
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** The scrubbed outcome of a verb over a tree: every value of the payload is masked in everything the outcome says. */
|
|
91
|
+
const scrubbed = <D>(o: Outcome<D>, tree: Interchange | undefined): Outcome<D> => (tree === undefined ? o : redactOutcome(o, redactor(valuesOf(tree).filter((v) => v.length >= 4))));
|
|
92
|
+
|
|
93
|
+
/** The verbs of Integrations. */
|
|
94
|
+
export function integrationsCommands(deps: Deps): readonly Command[] {
|
|
95
|
+
const connectorOf = (name: string | undefined): Connector | undefined => {
|
|
96
|
+
const id = parseConnectorId(name ?? "");
|
|
97
|
+
return id.kind === "ok" ? deps.connectors.get(id.value) : undefined;
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
const observe = command({
|
|
101
|
+
name: "observe",
|
|
102
|
+
summary: "Observe a system read-only and report the posture, assets and gaps.",
|
|
103
|
+
options: {},
|
|
104
|
+
operands: [{ name: "CONNECTOR", help: "The id of a connector.", arity: "one" }],
|
|
105
|
+
action: { kind: "report", reach: READ_ONLY },
|
|
106
|
+
run: async (args) => {
|
|
107
|
+
const c = connectorOf(args.positionals[0]);
|
|
108
|
+
if (c === undefined) return outcomeOf(null, { problems: [subject("such connector")] });
|
|
109
|
+
const port = await deps.readPort(c);
|
|
110
|
+
if (port.kind === "err") return outcomeOf(null, { problems: [problem("pending", `the credential ${c.governance.credential.ref} is not available (${port.error.kind})`, { code: "P010-CREDENTIAL", fix: "integrations probe" })] });
|
|
111
|
+
const o = await c.observe({ port: port.value, now: deps.clock.now() });
|
|
112
|
+
if (o.kind === "err") return outcomeOf(null, { problems: [problem("fail", `observing ${c.governance.id} failed: ${o.error.kind}`, { code: "E030-OBSERVE" })] });
|
|
113
|
+
const v = o.value;
|
|
114
|
+
return outcomeOf({ provider: v.provider, account: v.account, at: v.at, assets: v.assets.length, records: v.records?.length ?? 0, gaps: v.gaps, posture: v.posture }, { text: `${v.provider}: ${v.assets.length} assets, ${v.gaps.length} gaps` });
|
|
115
|
+
},
|
|
116
|
+
});
|
|
117
|
+
|
|
118
|
+
const probe = command({
|
|
119
|
+
name: "probe",
|
|
120
|
+
summary: "Check that a connector's credential reaches its system, reading one thing.",
|
|
121
|
+
options: {},
|
|
122
|
+
operands: [{ name: "CONNECTOR", help: "The id of a connector.", arity: "one" }],
|
|
123
|
+
action: { kind: "report", reach: READ_ONLY },
|
|
124
|
+
run: async (args) => {
|
|
125
|
+
const c = connectorOf(args.positionals[0]);
|
|
126
|
+
if (c === undefined) return outcomeOf(null, { problems: [subject("such connector")] });
|
|
127
|
+
const port = await deps.readPort(c);
|
|
128
|
+
if (port.kind === "err") return outcomeOf(null, { problems: [problem("pending", `the credential ${c.governance.credential.ref} is not available (${port.error.kind})`, { code: "P010-CREDENTIAL" })] });
|
|
129
|
+
const r = await c.probe({ port: port.value, now: deps.clock.now() });
|
|
130
|
+
return r.kind === "ok" ? outcomeOf({ reachable: true, account: r.value.account }, { text: `${c.governance.id} reaches ${r.value.account}` }) : outcomeOf(null, { problems: [problem("fail", `the probe of ${c.governance.id} failed: ${r.error.kind}`, { code: "E031-PROBE" })] });
|
|
131
|
+
},
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
const check = command({
|
|
135
|
+
name: "check",
|
|
136
|
+
summary: "Observe and judge the posture policies of a connector.",
|
|
137
|
+
options: {},
|
|
138
|
+
operands: [{ name: "CONNECTOR", help: "The id of a connector.", arity: "one" }],
|
|
139
|
+
action: { kind: "report", reach: READ_ONLY },
|
|
140
|
+
run: async (args) => {
|
|
141
|
+
const c = connectorOf(args.positionals[0]);
|
|
142
|
+
if (c === undefined) return outcomeOf(null, { problems: [subject("such connector")] });
|
|
143
|
+
const port = await deps.readPort(c);
|
|
144
|
+
if (port.kind === "err") return outcomeOf(null, { problems: [problem("pending", `the credential ${c.governance.credential.ref} is not available (${port.error.kind})`, { code: "P010-CREDENTIAL" })] });
|
|
145
|
+
const now = deps.clock.now();
|
|
146
|
+
const o = await c.observe({ port: port.value, now });
|
|
147
|
+
if (o.kind === "err") return outcomeOf(null, { problems: [problem("fail", `observing ${c.governance.id} failed: ${o.error.kind}`, { code: "E030-OBSERVE" })] });
|
|
148
|
+
const results = c.check(o.value, now);
|
|
149
|
+
const problems = results.flatMap((r) => (r.status === "fail" ? [problem("fail", `${r.id}: ${r.detail}`, { fix: r.fix, code: "E032-POSTURE" })] : r.status === "warn" ? [problem("warn", `${r.id}: ${r.detail}`, { fix: r.fix })] : []));
|
|
150
|
+
return outcomeOf({ results }, { problems, text: `${results.filter((r) => r.status === "pass").length} of ${results.length} policies pass` });
|
|
151
|
+
},
|
|
152
|
+
});
|
|
153
|
+
|
|
154
|
+
const validateVerb = command({
|
|
155
|
+
name: "validate",
|
|
156
|
+
summary: "Validate a document against a schema: syntax, schema and terminology findings, never the values.",
|
|
157
|
+
options: { schema: value<never>({ help: "The id of the schema to validate against.", required: true }) },
|
|
158
|
+
operands: [{ name: "FILE", help: "The document.", arity: "one" }],
|
|
159
|
+
action: { kind: "report", reach: READ_ONLY },
|
|
160
|
+
run: async (args) => {
|
|
161
|
+
const loaded = await load(deps, args.positionals[0] ?? "");
|
|
162
|
+
if (loaded.kind === "err") return loaded.error;
|
|
163
|
+
const schema = deps.schemas.get(args.options.schema);
|
|
164
|
+
if (schema === undefined) return outcomeOf(null, { problems: [subject(`schema ${args.options.schema}`)] });
|
|
165
|
+
const findings = transactionsOf(loaded.value.tree).flatMap((t) => validate(t, schema, { terminologies: deps.terminologies }));
|
|
166
|
+
return scrubbed(
|
|
167
|
+
outcomeOf({ findings, valid: !hasErrors(findings), transactions: transactionsOf(loaded.value.tree).length }, { problems: byLevel(findings), text: hasErrors(findings) ? `${findings.length} findings` : "valid" }),
|
|
168
|
+
loaded.value.tree,
|
|
169
|
+
);
|
|
170
|
+
},
|
|
171
|
+
});
|
|
172
|
+
|
|
173
|
+
const translate = command({
|
|
174
|
+
name: "translate",
|
|
175
|
+
summary: "Report what translating a document to another syntax would do; the document itself is written only to --out.",
|
|
176
|
+
options: { out: value<never>({ help: "Where to write the translated document." }) },
|
|
177
|
+
operands: [{ name: "FILE", help: "The document.", arity: "one" }],
|
|
178
|
+
action: { kind: "action", effect: "mutate", idempotent: true, reach: CHANGES },
|
|
179
|
+
run: async (args) => {
|
|
180
|
+
const loaded = await load(deps, args.positionals[0] ?? "");
|
|
181
|
+
if (loaded.kind === "err") return loaded.error;
|
|
182
|
+
const plugin = [...deps.plugins.values()].find((p) => p.id === loaded.value.pluginId);
|
|
183
|
+
const written = plugin === undefined ? undefined : plugin.codec.serialize(loaded.value.tree);
|
|
184
|
+
if (written === undefined || written.kind === "err") return outcomeOf(null, { problems: [problem("fail", "the document cannot be written", { code: "E101-SERIALIZE" })] });
|
|
185
|
+
if (args.options.out !== undefined) {
|
|
186
|
+
const w = await deps.writeFile(args.options.out, written.value);
|
|
187
|
+
if (w.kind === "err") return scrubbed(outcomeOf(null, { problems: [problem("fail", `${args.options.out} cannot be written`, { code: "E021-WRITE" })] }), loaded.value.tree);
|
|
188
|
+
}
|
|
189
|
+
return scrubbed(outcomeOf({ transactions: transactionsOf(loaded.value.tree).length, wrote: args.options.out !== undefined }, { text: "translated" }), loaded.value.tree);
|
|
190
|
+
},
|
|
191
|
+
});
|
|
192
|
+
|
|
193
|
+
const agreementOf = (name: string): ExchangeAgreement | undefined => {
|
|
194
|
+
const id = parseAgreementId(name);
|
|
195
|
+
return id.kind === "ok" ? deps.agreements.get(id.value) : undefined;
|
|
196
|
+
};
|
|
197
|
+
|
|
198
|
+
const send = command({
|
|
199
|
+
name: "send",
|
|
200
|
+
summary: "Send a document to a partner under an agreement: validate, deliver, and say where the exchange stands.",
|
|
201
|
+
options: { agreement: value<never>({ help: "The id of the agreement.", required: true }), schema: value<never>({ help: "The id of the schema to validate against." }) },
|
|
202
|
+
operands: [{ name: "FILE", help: "The document.", arity: "one" }],
|
|
203
|
+
action: { kind: "action", effect: "mutate", reach: CHANGES },
|
|
204
|
+
run: async (args) => {
|
|
205
|
+
const a = agreementOf(args.options.agreement);
|
|
206
|
+
if (a === undefined) return outcomeOf(null, { problems: [subject(`agreement ${args.options.agreement}`)] });
|
|
207
|
+
const loaded = await load(deps, args.positionals[0] ?? "");
|
|
208
|
+
if (loaded.kind === "err") return loaded.error;
|
|
209
|
+
const tree = loaded.value.tree;
|
|
210
|
+
const schema = args.options.schema === undefined ? undefined : deps.schemas.get(args.options.schema);
|
|
211
|
+
const findings = schema === undefined ? [] : transactionsOf(tree).flatMap((t) => validate(t, schema, { terminologies: deps.terminologies }));
|
|
212
|
+
if (hasErrors(findings)) return scrubbed(outcomeOf({ findings, state: "pending" }, { problems: byLevel(findings) }), tree);
|
|
213
|
+
const plugin = [...deps.plugins.values()].find((p) => p.id === loaded.value.pluginId);
|
|
214
|
+
const text = plugin === undefined ? undefined : plugin.codec.serialize(tree);
|
|
215
|
+
if (text === undefined || text.kind === "err") return scrubbed(outcomeOf(null, { problems: [problem("fail", "the document cannot be written", { code: "E101-SERIALIZE" })] }), tree);
|
|
216
|
+
const transport = await deps.transportOf(a);
|
|
217
|
+
if (transport.kind === "err") return scrubbed(outcomeOf(null, { problems: [problem("pending", `the credential ${a.credential} is not available`, { code: "P010-CREDENTIAL" })] }), tree);
|
|
218
|
+
const sent: Result<Delivered, TransportFailure> = await transport.value.send({ contentType: "application/octet-stream", body: text.value });
|
|
219
|
+
const at = deps.clock.now();
|
|
220
|
+
let state: ExchangeState = { kind: "pending" };
|
|
221
|
+
const s1 = transition(state, { kind: "send", at }, a.serviceLevels);
|
|
222
|
+
if (s1.kind === "ok") state = s1.value;
|
|
223
|
+
if (sent.kind === "err") {
|
|
224
|
+
const s2 = transition(state, { kind: "timeout" }, a.serviceLevels);
|
|
225
|
+
if (s2.kind === "ok") state = s2.value;
|
|
226
|
+
return scrubbed(outcomeOf({ state: state.kind, failure: sent.error.kind }, { problems: [problem("fail", `the partner was not reached (${sent.error.kind})`, { code: "E040-DELIVERY" })] }), tree);
|
|
227
|
+
}
|
|
228
|
+
return scrubbed(outcomeOf({ state: state.kind, status: sent.value.status }, { text: `sent to ${a.partner}` }), tree);
|
|
229
|
+
},
|
|
230
|
+
});
|
|
231
|
+
|
|
232
|
+
const receive = command({
|
|
233
|
+
name: "receive",
|
|
234
|
+
summary: "Receive a document under an agreement: read it, validate it and say what acknowledgement is due.",
|
|
235
|
+
options: { agreement: value<never>({ help: "The id of the agreement.", required: true }), schema: value<never>({ help: "The id of the schema to validate against." }) },
|
|
236
|
+
operands: [{ name: "FILE", help: "The document.", arity: "one" }],
|
|
237
|
+
action: { kind: "action", effect: "mutate", idempotent: true, reach: CHANGES },
|
|
238
|
+
run: async (args) => {
|
|
239
|
+
const a = agreementOf(args.options.agreement);
|
|
240
|
+
if (a === undefined) return outcomeOf(null, { problems: [subject(`agreement ${args.options.agreement}`)] });
|
|
241
|
+
const loaded = await load(deps, args.positionals[0] ?? "");
|
|
242
|
+
if (loaded.kind === "err") return loaded.error;
|
|
243
|
+
const tree = loaded.value.tree;
|
|
244
|
+
const schema = args.options.schema === undefined ? undefined : deps.schemas.get(args.options.schema);
|
|
245
|
+
const findings = schema === undefined ? [] : transactionsOf(tree).flatMap((t) => validate(t, schema, { terminologies: deps.terminologies }));
|
|
246
|
+
const ackStatus = hasErrors(findings) ? "rejected" : findings.length > 0 ? "accepted-with-errors" : "accepted";
|
|
247
|
+
let state: ExchangeState = { kind: "pending" };
|
|
248
|
+
const r = transition(state, { kind: "receive", at: deps.clock.now() }, a.serviceLevels);
|
|
249
|
+
if (r.kind === "ok") state = r.value;
|
|
250
|
+
const next = transition(state, { kind: "ack", status: ackStatus }, a.serviceLevels);
|
|
251
|
+
if (next.kind === "ok") state = next.value;
|
|
252
|
+
const due: readonly string[] = a.acknowledgements.map((x) => x.kind);
|
|
253
|
+
return scrubbed(outcomeOf({ findings, state: state.kind, acknowledge: ackStatus, due }, { problems: byLevel(findings), text: `received from ${a.partner}: ${ackStatus}` }), tree);
|
|
254
|
+
},
|
|
255
|
+
});
|
|
256
|
+
|
|
257
|
+
const explain = command({
|
|
258
|
+
name: "explain",
|
|
259
|
+
summary: "Explain a finding code, or what an acknowledgement means.",
|
|
260
|
+
options: {},
|
|
261
|
+
operands: [{ name: "CODE", help: "A finding code, such as cardinality-min.", arity: "one" }],
|
|
262
|
+
action: { kind: "report", reach: READ_ONLY },
|
|
263
|
+
run: (args) => {
|
|
264
|
+
const code = args.positionals[0] ?? "";
|
|
265
|
+
const text = isFindingCode(code) ? EXPLANATIONS[code] : undefined;
|
|
266
|
+
return Promise.resolve(text === undefined ? outcomeOf(null, { problems: [subject(`code ${code}`)] }) : outcomeOf({ code, explanation: text }, { text }));
|
|
267
|
+
},
|
|
268
|
+
});
|
|
269
|
+
|
|
270
|
+
return [observe, probe, check, validateVerb, translate, send, receive, explain];
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/** The program node `integrations`, with its verbs. */
|
|
274
|
+
export function integrationsBranch(deps: Deps) {
|
|
275
|
+
return branch({ name: "integrations", summary: "Observe systems read-only and exchange documents under standards.", children: integrationsCommands(deps) });
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/** An acknowledgement's status, re-exported for a surface that draws it. */
|
|
279
|
+
export const acknowledgementStatus = (a: Acknowledgement) => statusOf(a);
|
|
280
|
+
|
|
281
|
+
/** Exhaustive over the ways a delivery fails, for a surface that draws them. */
|
|
282
|
+
export function describeFailure(f: TransportFailure): string {
|
|
283
|
+
switch (f.kind) {
|
|
284
|
+
case "refused":
|
|
285
|
+
return "the request was refused before it was sent";
|
|
286
|
+
case "network":
|
|
287
|
+
return "the network gave no answer";
|
|
288
|
+
case "rejected":
|
|
289
|
+
return `the partner rejected it with status ${f.status}`;
|
|
290
|
+
default:
|
|
291
|
+
return absurd(f);
|
|
292
|
+
}
|
|
293
|
+
}
|