@effected/engine 0.1.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.
@@ -0,0 +1,51 @@
1
+ import { Context, Option, Schema } from "effect";
2
+
3
+ //#region src/Distribution.ts
4
+ /**
5
+ * The carrier package a tool's bins were installed through.
6
+ *
7
+ * @remarks
8
+ * A carrier (`@scope/plugin`) re-exposes its front ends' bins and passes its
9
+ * own identity down to each front end's `main`. A plain struct rather than a
10
+ * `Schema.Class`, because it travels in JSON envelopes as a plain object and
11
+ * is compared structurally.
12
+ *
13
+ * @public
14
+ */
15
+ const Distribution = Schema.Struct({
16
+ name: Schema.String,
17
+ version: Schema.String
18
+ });
19
+ /**
20
+ * The `distribution` field of a machine-readable envelope: `null` when the
21
+ * front end was installed directly rather than through a carrier.
22
+ *
23
+ * @public
24
+ */
25
+ const DistributionField = Schema.NullOr(Distribution);
26
+ /**
27
+ * The carrier this run was installed through, read anywhere without
28
+ * appearing in `R`.
29
+ *
30
+ * @remarks
31
+ * A `Context.Reference`, not a `Context.Service`: it carries its own default
32
+ * (`Option.none()`), so a direct install needs no provision at all. A front
33
+ * end's `main` provides it once, at the top of the program, with
34
+ * `Effect.provideService(CurrentDistribution, Option.fromNullishOr(options.distribution))`.
35
+ *
36
+ * @public
37
+ */
38
+ const CurrentDistribution = Context.Reference("@effected/engine/CurrentDistribution", { defaultValue: () => Option.none() });
39
+ /**
40
+ * The `via <name> <version>` suffix (prefixed with a space) a `--version`
41
+ * line or a startup log line appends, or `""` for a direct install.
42
+ *
43
+ * @public
44
+ */
45
+ const distributionSuffix = (distribution) => Option.match(distribution, {
46
+ onNone: () => "",
47
+ onSome: ({ name, version }) => ` via ${name} ${version}`
48
+ });
49
+
50
+ //#endregion
51
+ export { CurrentDistribution, Distribution, DistributionField, distributionSuffix };
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 C. Spencer Beggs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,45 @@
1
+ //#region src/LaunchContext.ts
2
+ /**
3
+ * Resolves where a tool launched by an agent host should treat as its project.
4
+ *
5
+ * @public
6
+ */
7
+ var LaunchContext = class LaunchContext {
8
+ constructor() {}
9
+ /**
10
+ * Whether a value still carries a literal `${VAR}` placeholder.
11
+ *
12
+ * @remarks
13
+ * Claude Code passes `${CLAUDE_PROJECT_DIR}` through unsubstituted in some
14
+ * launch paths; a path containing a placeholder is never what was meant.
15
+ */
16
+ static isUnsubstituted = (value) => {
17
+ const open = value.indexOf("${");
18
+ return open !== -1 && value.indexOf("}", open + 2) !== -1;
19
+ };
20
+ /**
21
+ * The first usable argv value, then the first usable env value in `keys`
22
+ * order, then `cwd`. A value is usable when it is non-empty after trimming
23
+ * and carries no placeholder — `??` would return an empty string or a literal
24
+ * `${VAR}`, which is the bug this replaces.
25
+ */
26
+ static projectDir = (input) => {
27
+ const usable = (value) => {
28
+ if (value === void 0) return void 0;
29
+ const trimmed = value.trim();
30
+ return trimmed === "" || LaunchContext.isUnsubstituted(trimmed) ? void 0 : trimmed;
31
+ };
32
+ for (const value of input.argv ?? []) {
33
+ const found = usable(value);
34
+ if (found !== void 0) return found;
35
+ }
36
+ for (const key of input.keys) {
37
+ const found = usable(input.env[key]);
38
+ if (found !== void 0) return found;
39
+ }
40
+ return input.cwd;
41
+ };
42
+ };
43
+
44
+ //#endregion
45
+ export { LaunchContext };
package/README.md ADDED
@@ -0,0 +1,99 @@
1
+ # @effected/engine
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/)
7
+
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.
9
+
10
+ > **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
11
+ > development against a single pinned Effect v4 prerelease. Packages graduate to
12
+ > `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
13
+ > exactly the ones 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)
package/Remediation.js ADDED
@@ -0,0 +1,23 @@
1
+ import { Schema } from "effect";
2
+
3
+ //#region src/Remediation.ts
4
+ /**
5
+ * What a caller — usually an agent — should do after a failure.
6
+ *
7
+ * @remarks
8
+ * The superset of two shapes consumers built independently: the folded-message
9
+ * shape `{ hint, suggestedTool? }` and the structured-data shape
10
+ * `{ suggestedTool, suggestedArgs, humanHint }`. `humanHint` maps to `hint`.
11
+ * Keys are `optionalKey`, so an explicit `undefined` is rejected rather than
12
+ * silently encoded.
13
+ *
14
+ * @public
15
+ */
16
+ const Remediation = Schema.Struct({
17
+ hint: Schema.String,
18
+ suggestedTool: Schema.optionalKey(Schema.String),
19
+ suggestedArgs: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown))
20
+ });
21
+
22
+ //#endregion
23
+ export { Remediation };
package/index.d.ts ADDED
@@ -0,0 +1,131 @@
1
+ import { Context, Option, Schema } from "effect";
2
+ //#region src/Distribution.d.ts
3
+ /**
4
+ * The carrier package a tool's bins were installed through.
5
+ *
6
+ * @remarks
7
+ * A carrier (`@scope/plugin`) re-exposes its front ends' bins and passes its
8
+ * own identity down to each front end's `main`. A plain struct rather than a
9
+ * `Schema.Class`, because it travels in JSON envelopes as a plain object and
10
+ * is compared structurally.
11
+ *
12
+ * @public
13
+ */
14
+ export declare const Distribution: Schema.Struct<{
15
+ readonly name: Schema.String;
16
+ readonly version: Schema.String;
17
+ }>;
18
+ /**
19
+ * A decoded {@link (Distribution:variable)}.
20
+ *
21
+ * @public
22
+ */
23
+ export type Distribution = typeof Distribution.Type;
24
+ /**
25
+ * The `distribution` field of a machine-readable envelope: `null` when the
26
+ * front end was installed directly rather than through a carrier.
27
+ *
28
+ * @public
29
+ */
30
+ export declare const DistributionField: Schema.NullOr<Schema.Struct<{
31
+ readonly name: Schema.String;
32
+ readonly version: Schema.String;
33
+ }>>;
34
+ /**
35
+ * The carrier this run was installed through, read anywhere without
36
+ * appearing in `R`.
37
+ *
38
+ * @remarks
39
+ * A `Context.Reference`, not a `Context.Service`: it carries its own default
40
+ * (`Option.none()`), so a direct install needs no provision at all. A front
41
+ * end's `main` provides it once, at the top of the program, with
42
+ * `Effect.provideService(CurrentDistribution, Option.fromNullishOr(options.distribution))`.
43
+ *
44
+ * @public
45
+ */
46
+ export declare const CurrentDistribution: Context.Reference<Option.Option<Distribution>>;
47
+ /**
48
+ * The `via <name> <version>` suffix (prefixed with a space) a `--version`
49
+ * line or a startup log line appends, or `""` for a direct install.
50
+ *
51
+ * @public
52
+ */
53
+ export declare const distributionSuffix: (distribution: Option.Option<Distribution>) => string;
54
+ //#endregion
55
+ //#region src/LaunchContext.d.ts
56
+ /**
57
+ * The process-derived facts a front end resolves once, passed in as values.
58
+ *
59
+ * @remarks
60
+ * Nothing here reads `process`: `argv`, `env` and `cwd` come from the front
61
+ * end's own `main.ts`. That keeps the resolution rule shared and testable
62
+ * while the process read stays at the one place allowed to make it.
63
+ *
64
+ * @public
65
+ */
66
+ interface ProjectDirInput {
67
+ /**
68
+ * Positional candidates, checked in order. Pass positional arguments only —
69
+ * the parsed positionals of your command, never raw `process.argv.slice(2)`:
70
+ * every non-empty value counts as a candidate, so a `--flag` would become the
71
+ * project directory.
72
+ */
73
+ readonly argv?: ReadonlyArray<string> | undefined;
74
+ /** The environment, usually `process.env`. */
75
+ readonly env: Readonly<Record<string, string | undefined>>;
76
+ /** Env keys to try in order, for example `["OKFIT_PROJECT_DIR", "CLAUDE_PROJECT_DIR"]`. */
77
+ readonly keys: ReadonlyArray<string>;
78
+ /** The fallback, usually `process.cwd()`. */
79
+ readonly cwd: string;
80
+ }
81
+ /**
82
+ * Resolves where a tool launched by an agent host should treat as its project.
83
+ *
84
+ * @public
85
+ */
86
+ export declare class LaunchContext {
87
+ private constructor();
88
+ /**
89
+ * Whether a value still carries a literal `${VAR}` placeholder.
90
+ *
91
+ * @remarks
92
+ * Claude Code passes `${CLAUDE_PROJECT_DIR}` through unsubstituted in some
93
+ * launch paths; a path containing a placeholder is never what was meant.
94
+ */
95
+ static readonly isUnsubstituted: (value: string) => boolean;
96
+ /**
97
+ * The first usable argv value, then the first usable env value in `keys`
98
+ * order, then `cwd`. A value is usable when it is non-empty after trimming
99
+ * and carries no placeholder — `??` would return an empty string or a literal
100
+ * `${VAR}`, which is the bug this replaces.
101
+ */
102
+ static readonly projectDir: (input: ProjectDirInput) => string;
103
+ }
104
+ //#endregion
105
+ //#region src/Remediation.d.ts
106
+ /**
107
+ * What a caller — usually an agent — should do after a failure.
108
+ *
109
+ * @remarks
110
+ * The superset of two shapes consumers built independently: the folded-message
111
+ * shape `{ hint, suggestedTool? }` and the structured-data shape
112
+ * `{ suggestedTool, suggestedArgs, humanHint }`. `humanHint` maps to `hint`.
113
+ * Keys are `optionalKey`, so an explicit `undefined` is rejected rather than
114
+ * silently encoded.
115
+ *
116
+ * @public
117
+ */
118
+ export declare const Remediation: Schema.Struct<{
119
+ readonly hint: Schema.String;
120
+ readonly suggestedTool: Schema.optionalKey<Schema.String>;
121
+ readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
122
+ }>;
123
+ /**
124
+ * A decoded {@link (Remediation:variable)}.
125
+ *
126
+ * @public
127
+ */
128
+ export type Remediation = typeof Remediation.Type;
129
+ //#endregion
130
+ export type { ProjectDirInput };
131
+ //# sourceMappingURL=index.d.ts.map
package/index.js ADDED
@@ -0,0 +1,5 @@
1
+ import { CurrentDistribution, Distribution, DistributionField, distributionSuffix } from "./Distribution.js";
2
+ import { LaunchContext } from "./LaunchContext.js";
3
+ import { Remediation } from "./Remediation.js";
4
+
5
+ export { CurrentDistribution, Distribution, DistributionField, LaunchContext, Remediation, distributionSuffix };
package/package.json ADDED
@@ -0,0 +1,45 @@
1
+ {
2
+ "name": "@effected/engine",
3
+ "version": "0.1.0",
4
+ "private": false,
5
+ "description": "Platform-free primitives shared by every front end of an Effect v4 tool: distribution identity, remediation, and launch context",
6
+ "keywords": [
7
+ "effect",
8
+ "cli",
9
+ "mcp",
10
+ "carrier",
11
+ "distribution",
12
+ "effected"
13
+ ],
14
+ "homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/engine#readme",
15
+ "bugs": {
16
+ "url": "https://github.com/spencerbeggs/effected/issues"
17
+ },
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/spencerbeggs/effected.git",
21
+ "directory": "packages/engine"
22
+ },
23
+ "license": "MIT",
24
+ "author": {
25
+ "name": "C. Spencer Beggs",
26
+ "email": "spencer@beggs.codes",
27
+ "url": "https://spencerbeg.gs"
28
+ },
29
+ "sideEffects": false,
30
+ "type": "module",
31
+ "exports": {
32
+ ".": {
33
+ "types": "./index.d.ts",
34
+ "import": "./index.js",
35
+ "default": "./index.js"
36
+ },
37
+ "./package.json": "./package.json"
38
+ },
39
+ "peerDependencies": {
40
+ "effect": "4.0.0-rc.117"
41
+ },
42
+ "engines": {
43
+ "node": ">=24.11.0"
44
+ }
45
+ }
@@ -0,0 +1,11 @@
1
+ // This file is read by tools that parse documentation comments conforming to the TSDoc standard.
2
+ // It should be published with your NPM package. It should not be tracked by Git.
3
+ {
4
+ "tsdocVersion": "0.12",
5
+ "toolPackages": [
6
+ {
7
+ "packageName": "@microsoft/api-extractor",
8
+ "packageVersion": "7.59.1"
9
+ }
10
+ ]
11
+ }