@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 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
- [![npm](https://img.shields.io/npm/v/@effected%2Fengine?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/engine)
4
- [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
5
- [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
6
- [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
3
+ The `effected` tool's shared logic, consumed by its CLI and MCP front ends.
7
4
 
8
- Platform-free primitives shared by every front end of an Effect v4 tool. A carrier-pattern tool (a CLI, an MCP server, an LSP server) ships more than one bin behind one meta-package, and every one of those front ends needs to answer the same handful of questions the same way: which carrier was I installed through, and what version line does that make me. This package holds those primitives once, so a consumer's own `engine` package can depend on them without also depending on `@effected/cli` or any other front end.
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`.** This package is part of the `@effected/*` kit, built on stable
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.