@effected/engine 0.10.0 → 0.12.0
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/Identity.js +55 -0
- package/README.md +3 -95
- package/index.d.ts +30 -486
- package/index.js +2 -7
- package/package.json +6 -11
- package/tsdoc-metadata.json +1 -1
- package/Distribution.js +0 -90
- package/ErrorText.js +0 -98
- package/Exclusive.js +0 -141
- package/LaunchContext.js +0 -90
- package/ProcessGuard.js +0 -144
- package/ProcessScope.js +0 -95
- package/Remediation.js +0 -33
- package/guard.d.ts +0 -205
- package/guard.js +0 -3
- package/internal/causeMessage.js +0 -57
package/Identity.js
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { DistributionField } from "@effected/kit";
|
|
2
|
+
import { Effect, Schema } from "effect";
|
|
3
|
+
import effectPackage from "effect/package.json" with { type: "json" };
|
|
4
|
+
|
|
5
|
+
// src/Identity.ts
|
|
6
|
+
/**
|
|
7
|
+
* What the `effected` tool reports about itself.
|
|
8
|
+
*
|
|
9
|
+
* @public
|
|
10
|
+
*/
|
|
11
|
+
var IdentityReport = class extends Schema.Class("IdentityReport")({
|
|
12
|
+
/** The tool name; always `"effected"`. */
|
|
13
|
+
tool: Schema.Literal("effected"),
|
|
14
|
+
/** The reporting front end's own version. */
|
|
15
|
+
version: Schema.String,
|
|
16
|
+
/** The carrier distribution the front end was installed through, or `null` for a direct install. */
|
|
17
|
+
distribution: DistributionField,
|
|
18
|
+
/** The resolved `effect` package version. */
|
|
19
|
+
effect: Schema.String
|
|
20
|
+
}) {};
|
|
21
|
+
/**
|
|
22
|
+
* The `effected` tool's identity program.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```ts
|
|
26
|
+
* import { Effect } from "effect"
|
|
27
|
+
* import { Identity } from "@effected/engine"
|
|
28
|
+
*
|
|
29
|
+
* const program = Effect.gen(function* () {
|
|
30
|
+
* const report = yield* Identity.report({ version: "0.12.0", distribution: null })
|
|
31
|
+
* // { tool: "effected", version: "0.12.0", distribution: null, effect: "<the resolved effect version>" }
|
|
32
|
+
* return report
|
|
33
|
+
* })
|
|
34
|
+
* ```
|
|
35
|
+
*
|
|
36
|
+
* @public
|
|
37
|
+
*/
|
|
38
|
+
var Identity = class {
|
|
39
|
+
constructor() {}
|
|
40
|
+
/**
|
|
41
|
+
* Build the identity report for a front end.
|
|
42
|
+
*
|
|
43
|
+
* @remarks
|
|
44
|
+
* `options.version` is the front end's own version and `options.distribution` the carrier it was installed
|
|
45
|
+
* through, or `null`. The `effect` field is read from the resolved `effect` package.
|
|
46
|
+
*/
|
|
47
|
+
static report = (options) => Effect.sync(() => IdentityReport.make({
|
|
48
|
+
tool: "effected",
|
|
49
|
+
version: options.version,
|
|
50
|
+
distribution: options.distribution,
|
|
51
|
+
effect: effectPackage.version
|
|
52
|
+
}));
|
|
53
|
+
};
|
|
54
|
+
|
|
55
|
+
export { Identity, IdentityReport };
|
package/README.md
CHANGED
|
@@ -1,99 +1,7 @@
|
|
|
1
1
|
# @effected/engine
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](https://opensource.org/licenses/MIT)
|
|
5
|
-
[](https://nodejs.org/)
|
|
6
|
-
[](https://www.typescriptlang.org/)
|
|
3
|
+
The `effected` tool's shared logic, consumed by its CLI and MCP front ends.
|
|
7
4
|
|
|
8
|
-
|
|
5
|
+
The first release reports identity only: `Identity.report({ version, distribution })` returns an `IdentityReport` carrying the tool name, the front end's own version, its carrier distribution (or `null`), and the resolved `effect` version.
|
|
9
6
|
|
|
10
|
-
> **Pre-`1.0.0`.**
|
|
11
|
-
> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
|
|
12
|
-
> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
|
|
13
|
-
> `@effect/*` versions on the line the kit is built and tested against, install
|
|
14
|
-
> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
|
|
15
|
-
>
|
|
16
|
-
> **Stability: unstable.** This package's API surface is not yet considered
|
|
17
|
-
> complete and may change across `0.x` releases. Pin an exact version — even a
|
|
18
|
-
> package marked *stable* before `1.0.0` can introduce a breaking change by
|
|
19
|
-
> accident, and an exact pin turns that into a type-check error rather than a
|
|
20
|
-
> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
|
|
21
|
-
|
|
22
|
-
## Install
|
|
23
|
-
|
|
24
|
-
```bash
|
|
25
|
-
npm install @effected/engine effect
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
pnpm add @effected/engine effect
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
Requires Node.js >=24.11.0.
|
|
33
|
-
|
|
34
|
-
All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
|
|
35
|
-
|
|
36
|
-
`effect` v4 is the only peer dependency, and it is the only dependency of any kind — no parser, no polyfill, no platform package rides in behind it. There is no IO here: every export is a schema, a reference with a default, or a pure function.
|
|
37
|
-
|
|
38
|
-
## Distribution
|
|
39
|
-
|
|
40
|
-
`Distribution` is the carrier package a tool's bins were installed through — its `name` and `version`. A plain `Schema.Struct` rather than a `Schema.Class`, because it travels as a plain object inside a machine-readable envelope and is compared structurally, never constructed on its own.
|
|
41
|
-
|
|
42
|
-
```ts
|
|
43
|
-
import { Distribution } from "@effected/engine";
|
|
44
|
-
import { Schema } from "effect";
|
|
45
|
-
|
|
46
|
-
const decoded = Schema.decodeUnknownSync(Distribution)({ name: "@okfit/plugin", version: "0.5.1" });
|
|
47
|
-
console.log(decoded);
|
|
48
|
-
// => { name: "@okfit/plugin", version: "0.5.1" }
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
`DistributionField` is the `distribution` field of an envelope: `Schema.NullOr(Distribution)`, where `null` means the front end was installed directly rather than through a carrier — not "not yet known."
|
|
52
|
-
|
|
53
|
-
## CurrentDistribution
|
|
54
|
-
|
|
55
|
-
`CurrentDistribution` is a `Context.Reference<Option<Distribution>>`, not a `Context.Service`: it carries its own default (`Option.none()`), so reading it never appears in an effect's `R` and a direct install needs no provision at all. A front end's `main` provides it once, at the top of the program, once it has resolved what installed it.
|
|
56
|
-
|
|
57
|
-
```ts
|
|
58
|
-
import { CurrentDistribution } from "@effected/engine";
|
|
59
|
-
import { Effect, Option } from "effect";
|
|
60
|
-
|
|
61
|
-
const program = Effect.gen(function* () {
|
|
62
|
-
const current = yield* CurrentDistribution;
|
|
63
|
-
return Option.isSome(current) ? current.value.name : "direct install";
|
|
64
|
-
});
|
|
65
|
-
|
|
66
|
-
console.log(Effect.runSync(program));
|
|
67
|
-
// => "direct install"
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
Providing a value scopes it to the sub-effect, the same way any `Context.Reference` scopes:
|
|
71
|
-
|
|
72
|
-
```ts
|
|
73
|
-
program.pipe(
|
|
74
|
-
Effect.provideService(CurrentDistribution, Option.some({ name: "@okfit/plugin", version: "0.5.1" })),
|
|
75
|
-
);
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
## distributionSuffix
|
|
79
|
-
|
|
80
|
-
`distributionSuffix` turns a `CurrentDistribution` read into the trailing text a `--version` line or a startup log line appends — `""` for a direct install, `" via <name> <version>"` for a carrier. A free function, not a static on `Distribution`, because a `Schema.Struct` value carries no statics to hang it from.
|
|
81
|
-
|
|
82
|
-
```ts
|
|
83
|
-
import { distributionSuffix } from "@effected/engine";
|
|
84
|
-
import { Option } from "effect";
|
|
85
|
-
|
|
86
|
-
distributionSuffix(Option.none());
|
|
87
|
-
// => ""
|
|
88
|
-
|
|
89
|
-
distributionSuffix(Option.some({ name: "@okfit/plugin", version: "0.5.1" }));
|
|
90
|
-
// => " via @okfit/plugin 0.5.1"
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
## Tier
|
|
94
|
-
|
|
95
|
-
Pure tier: `effect` is the only peer, no `process`, no `node:` import, no platform package. Nothing in the kit depends on `@effected/engine` except `@effected/mcp`; `@effected/cli` never does — the two sit at the same layer, both consumed by a front end, never by each other.
|
|
96
|
-
|
|
97
|
-
## License
|
|
98
|
-
|
|
99
|
-
[MIT](LICENSE)
|
|
7
|
+
> **Pre-`1.0.0`.** Part of the `@effected/*` kit; unstable across `0.x` releases. Pin an exact version.
|