@effected/engine 0.8.0 → 0.9.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/Distribution.js CHANGED
@@ -1,4 +1,4 @@
1
- import { Context, Option, Schema } from "effect";
1
+ import { Context, Effect, Option, Schema } from "effect";
2
2
 
3
3
  // src/Distribution.ts
4
4
  /**
@@ -46,5 +46,45 @@ const distributionSuffix = (distribution) => Option.match(distribution, {
46
46
  onNone: () => "",
47
47
  onSome: ({ name, version }) => ` via ${name} ${version}`
48
48
  });
49
+ /**
50
+ * Decorates a `--version` line formatter so its line ends with
51
+ * {@link distributionSuffix}: `formatVersion(name, version)` followed by
52
+ * a space and `via <carrier> <version>` when installed through a carrier,
53
+ * unchanged for a direct install.
54
+ *
55
+ * @remarks
56
+ * Shaped around `effect/cli`'s `CliOutput.Formatter["formatVersion"]`: it
57
+ * wraps whatever formatter is in effect (a coloured default or a custom one)
58
+ * rather than replacing it. The suffix is computed once, when the decorator is
59
+ * applied, because the distribution is known at `main`. Data-last, for `pipe`.
60
+ *
61
+ * @example
62
+ * ```ts
63
+ * import { withDistributionVersion } from "@effected/engine";
64
+ * import { Option } from "effect";
65
+ *
66
+ * const formatVersion = withDistributionVersion(Option.some({ name: "@scope/plugin", version: "2.0.0" }))(
67
+ * (name, version) => `${name} ${version}`,
68
+ * );
69
+ * formatVersion("tool", "1.0.0"); // "tool 1.0.0 via @scope/plugin 2.0.0"
70
+ * ```
71
+ *
72
+ * @public
73
+ */
74
+ const withDistributionVersion = (distribution) => {
75
+ const suffix = distributionSuffix(distribution);
76
+ return (formatVersion) => (name, version) => `${formatVersion(name, version)}${suffix}`;
77
+ };
78
+ /**
79
+ * Provides {@link CurrentDistribution} to `self`: `Option.some` of a carrier,
80
+ * `Option.none()` for `null` or `undefined` (a direct install).
81
+ *
82
+ * @remarks
83
+ * The one-line form of what a front end's `main` does once at the top of its
84
+ * program. Data-last, for `pipe`.
85
+ *
86
+ * @public
87
+ */
88
+ const withDistribution = (distribution) => (self) => Effect.provideService(self, CurrentDistribution, Option.fromNullishOr(distribution));
49
89
 
50
- export { CurrentDistribution, Distribution, DistributionField, distributionSuffix };
90
+ export { CurrentDistribution, Distribution, DistributionField, distributionSuffix, withDistribution, withDistributionVersion };
package/Exclusive.js ADDED
@@ -0,0 +1,141 @@
1
+ import { Duration, Effect, Schema, Semaphore } from "effect";
2
+
3
+ // src/Exclusive.ts
4
+ /**
5
+ * The body of an {@link Exclusive.run} call ran past its timeout and was
6
+ * interrupted. Its finalizers had run, and the permit was released, by the
7
+ * time the caller sees this.
8
+ *
9
+ * @remarks
10
+ * Audience: calling code, which usually folds it into its own outcome (a tool
11
+ * result's `{ kind: "timeout" }`). `timeout` is the formatted duration.
12
+ *
13
+ * @public
14
+ */
15
+ var ExclusiveTimeout = class extends Schema.TaggedError()("ExclusiveTimeout", {
16
+ timeout: Schema.String,
17
+ message: Schema.String
18
+ }) {};
19
+ /**
20
+ * A one-permit lane for work that mutates process-global state (the working
21
+ * directory, the environment, a patched stream), so two requests never
22
+ * interleave it and the state is restored before the next one starts.
23
+ *
24
+ * @remarks
25
+ * Ordering, on every exit path:
26
+ *
27
+ * 1. Waiting for the permit is interruptible: a request cancelled while it is
28
+ * queued leaves the queue and never runs.
29
+ * 2. Once the permit is held, the caller's interruption is masked until the
30
+ * body ends. A transport that maps a client cancel to an interrupt (an MCP
31
+ * server does) only drops the response; the next request still waits for
32
+ * the real work to finish.
33
+ * 3. The required timeout interrupts the body, and only the body.
34
+ * 4. The body runs in its own `Scope`: its finalizers (restoring the working
35
+ * directory or the environment with {@link ProcessScope}, removing a temp
36
+ * directory) run, then the permit is released, then the caller sees the
37
+ * result, an {@link ExclusiveTimeout}, or its own deferred interruption.
38
+ *
39
+ * A body that ignores interruption delays its timeout and the permit release
40
+ * until it settles, as an uninterruptible region does. That is
41
+ * deliberate, because releasing the permit while process state is still being
42
+ * changed is the bug this lane exists to prevent. Run promise work through
43
+ * {@link Exclusive.promise}, whose interruption aborts the signal and then
44
+ * waits for the promise to settle; `Effect.promise` would abandon it. A
45
+ * promise that ignores its signal and never settles therefore hangs the
46
+ * timeout and the permit forever: give it `abandon: true`.
47
+ *
48
+ * **Not reentrant.** A `run` on the same lane from inside a body waits for the
49
+ * permit its own caller holds. It never gets it: the nested call waits until
50
+ * the outer timeout fires, which interrupts the body (and the nested wait with
51
+ * it), so the outer `run` fails with {@link ExclusiveTimeout}. Call the inner
52
+ * work directly instead of through the lane again.
53
+ *
54
+ * @example
55
+ * ```ts
56
+ * import { Exclusive, ProcessScope } from "@effected/engine"
57
+ * import { Effect } from "effect"
58
+ *
59
+ * const lane = yield* Exclusive.make
60
+ * const result = yield* lane.run(
61
+ * Effect.gen(function* () {
62
+ * yield* ProcessScope.chdir(process, root)
63
+ * return yield* Exclusive.promise({ try: (signal) => runTool(signal), catch: (cause) => new ToolFailed({ cause }) })
64
+ * }),
65
+ * { timeout: "2 minutes" },
66
+ * )
67
+ * ```
68
+ *
69
+ * @public
70
+ */
71
+ var Exclusive = class Exclusive {
72
+ semaphore;
73
+ constructor(semaphore) {
74
+ this.semaphore = semaphore;
75
+ }
76
+ /** A new lane with one permit. Bind it once (a module-level or layer-built value); every call shares it. */
77
+ static make = Effect.map(Semaphore.make(1), (semaphore) => new Exclusive(semaphore));
78
+ /**
79
+ * A promise whose interruption aborts `signal` and then waits for the
80
+ * promise to settle, rather than abandoning it as `Effect.promise` and
81
+ * `Effect.tryPromise` do. A rejection, or a synchronous throw from `try`,
82
+ * fails through `catch`; a `catch` that itself throws dies with what it
83
+ * threw.
84
+ *
85
+ * @remarks
86
+ * **The default hangs on a promise that ignores its signal.** Waiting is
87
+ * the point: the interrupt (a lane timeout, a cancel) returns only once the
88
+ * promise has settled, so no work is still changing process state when the
89
+ * permit is released. But a promise that never observes `signal` and never
90
+ * settles (a test runner's `start`, a third-party call with no
91
+ * cancellation) holds the interrupt, the lane's timeout and the permit
92
+ * forever.
93
+ *
94
+ * Pass `abandon: true` for such a promise. Interruption still aborts
95
+ * `signal`, then resumes at once without waiting; the promise keeps running
96
+ * unobserved and its eventual result is dropped. Inside {@link Exclusive.run}
97
+ * the body's scope still closes, and its finalizers still run, before the
98
+ * permit is released. What abandoning gives up is the guarantee that the
99
+ * promise itself has stopped: choose it only when the promise cannot be
100
+ * stopped, and restore any state it touches in a finalizer.
101
+ */
102
+ static promise = (options) => Effect.callback((resume, signal) => {
103
+ const failure = (cause) => {
104
+ try {
105
+ return Effect.fail(options.catch(cause));
106
+ } catch (error) {
107
+ return Effect.die(error);
108
+ }
109
+ };
110
+ let settled;
111
+ try {
112
+ settled = Promise.resolve(options.try(signal));
113
+ } catch (cause) {
114
+ resume(failure(cause));
115
+ return;
116
+ }
117
+ settled.then((value) => resume(Effect.succeed(value)), (cause) => resume(failure(cause)));
118
+ if (options.abandon === true) return;
119
+ return Effect.promise(() => settled.then(() => void 0, () => void 0));
120
+ });
121
+ /**
122
+ * Runs `body` holding this lane's permit, under the ordering in the class
123
+ * remarks. `body` gets its own `Scope`, closed before the permit is released.
124
+ */
125
+ run = (body, options) => {
126
+ const timeout = Duration.fromInputUnsafe(options.timeout);
127
+ const lane = Effect.interruptible(Effect.scoped(body)).pipe(Effect.timeoutOrElse({
128
+ duration: timeout,
129
+ orElse: () => {
130
+ const formatted = Duration.format(timeout);
131
+ return Effect.fail(new ExclusiveTimeout({
132
+ timeout: formatted,
133
+ message: `Timed out after ${formatted}.`
134
+ }));
135
+ }
136
+ }));
137
+ return this.semaphore.withPermit(Effect.uninterruptible(lane)).pipe(Effect.withSpan("Exclusive.run"));
138
+ };
139
+ };
140
+
141
+ export { Exclusive, ExclusiveTimeout };
package/LaunchContext.js CHANGED
@@ -1,3 +1,5 @@
1
+ import { Option } from "effect";
2
+
1
3
  // src/LaunchContext.ts
2
4
  /**
3
5
  * Resolves where a tool launched by an agent host should treat as its project.
@@ -31,27 +33,58 @@ var LaunchContext = class LaunchContext {
31
33
  return open !== -1 && value.indexOf("}", open + 2) !== -1;
32
34
  };
33
35
  /**
34
- * The first usable argv value, then the first usable env value in `keys`
35
- * order, then `cwd`. A value is usable when it is non-empty after trimming
36
- * and carries no placeholder — `??` would return an empty string or a literal
37
- * `${VAR}`, neither of which names a directory.
36
+ * `value` trimmed, when it names something: `Option.none()` for `undefined`,
37
+ * an empty or whitespace-only string, or a string still carrying a literal
38
+ * `${VAR}` placeholder ({@link LaunchContext.isUnsubstituted}).
39
+ *
40
+ * @remarks
41
+ * The guard every resolver here applies; use it directly for one positional
42
+ * argument, as in `LaunchContext.usable(argv[2])`. `??` would accept an empty
43
+ * string or a literal `${VAR}`, neither of which names a directory or an id.
44
+ */
45
+ static usable = (value) => {
46
+ if (value === void 0) return Option.none();
47
+ const trimmed = value.trim();
48
+ return trimmed === "" || LaunchContext.isUnsubstituted(trimmed) ? Option.none() : Option.some(trimmed);
49
+ };
50
+ /**
51
+ * The first {@link LaunchContext.usable} `argv` value, then the first usable
52
+ * `env` value in `keys` order; `Option.none()` when none is usable.
53
+ *
54
+ * @remarks
55
+ * The resolver under {@link LaunchContext.projectDir}, without its `cwd`
56
+ * fallback, for any launch-supplied location: a host's plugin data
57
+ * directory, then an app override, with the caller's own fallback after
58
+ * it. Values are trimmed, so a value with surrounding whitespace resolves to
59
+ * the trimmed path.
60
+ *
61
+ * @example
62
+ * ```ts
63
+ * import { LaunchContext } from "@effected/engine"
64
+ * import { Option } from "effect"
65
+ *
66
+ * const dataDir = LaunchContext.resolve({ env, keys: ["CLAUDE_PLUGIN_DATA", "MYTOOL_DATA_DIR"] }).pipe(
67
+ * Option.getOrElse(() => `${home}/.mytool`),
68
+ * )
69
+ * ```
38
70
  */
39
- static projectDir = (input) => {
40
- const usable = (value) => {
41
- if (value === void 0) return void 0;
42
- const trimmed = value.trim();
43
- return trimmed === "" || LaunchContext.isUnsubstituted(trimmed) ? void 0 : trimmed;
44
- };
71
+ static resolve = (input) => {
45
72
  for (const value of input.argv ?? []) {
46
- const found = usable(value);
47
- if (found !== void 0) return found;
73
+ const found = LaunchContext.usable(value);
74
+ if (Option.isSome(found)) return found;
48
75
  }
49
76
  for (const key of input.keys) {
50
- const found = usable(input.env[key]);
51
- if (found !== void 0) return found;
77
+ const found = LaunchContext.usable(input.env[key]);
78
+ if (Option.isSome(found)) return found;
52
79
  }
53
- return input.cwd;
80
+ return Option.none();
54
81
  };
82
+ /**
83
+ * The first usable argv value, then the first usable env value in `keys`
84
+ * order, then `cwd`: {@link LaunchContext.resolve} with `cwd` as the
85
+ * fallback.
86
+ */
87
+ static projectDir = (input) => Option.getOrElse(LaunchContext.resolve(input), () => input.cwd);
55
88
  };
56
89
 
57
90
  export { LaunchContext };
@@ -0,0 +1,95 @@
1
+ import { Effect, Option, Schema } from "effect";
2
+
3
+ // src/ProcessScope.ts
4
+ /**
5
+ * A {@link ProcessScope} change could not be made.
6
+ *
7
+ * @remarks
8
+ * Audience: calling code (`reason`, `path`) and an end user (`message`).
9
+ * `"ChdirFailed"` means `chdir` threw for `path`; the original throw is
10
+ * `cause`. Nothing was changed, so nothing is restored.
11
+ *
12
+ * @public
13
+ */
14
+ var ProcessScopeError = class extends Schema.TaggedError()("ProcessScopeError", {
15
+ reason: Schema.Literal("ChdirFailed"),
16
+ path: Schema.String,
17
+ message: Schema.String,
18
+ cause: Schema.Defect()
19
+ }) {};
20
+ /**
21
+ * Scoped changes to process-global state, each restored when the enclosing
22
+ * `Scope` closes, on every exit path.
23
+ *
24
+ * @remarks
25
+ * Pair them with {@link Exclusive}: a scoped restore protects the next request
26
+ * only if no other request can run while the change is live.
27
+ *
28
+ * Both take the state they change as an argument (a {@link ProcessCwdHost},
29
+ * an environment record), so they read no `process` and test against plain
30
+ * doubles. For a temporary directory, use core's
31
+ * `FileSystem.makeTempDirectory` in an `Effect.acquireRelease` whose release
32
+ * ignores a failed removal; `makeTempDirectoryScoped`'s release dies on one,
33
+ * which turns a successful body into a defect.
34
+ *
35
+ * @public
36
+ */
37
+ var ProcessScope = class {
38
+ constructor() {}
39
+ /**
40
+ * Enters `directory` and returns to the previous working directory when the
41
+ * scope closes.
42
+ *
43
+ * @remarks
44
+ * When the previous directory cannot be read (it was deleted, so `cwd()`
45
+ * throws), the change still happens and nothing is restored: there is no
46
+ * valid directory to go back to. A restore that throws is ignored for the
47
+ * same reason.
48
+ */
49
+ static chdir = (host, directory) => Effect.asVoid(Effect.acquireRelease(Effect.try({
50
+ try: () => {
51
+ let previous;
52
+ try {
53
+ previous = Option.some(host.cwd());
54
+ } catch {
55
+ previous = Option.none();
56
+ }
57
+ host.chdir(directory);
58
+ return previous;
59
+ },
60
+ catch: (cause) => new ProcessScopeError({
61
+ reason: "ChdirFailed",
62
+ path: directory,
63
+ message: `Cannot change the working directory to ${directory}.`,
64
+ cause
65
+ })
66
+ }), (previous) => Effect.sync(() => {
67
+ if (Option.isNone(previous)) return;
68
+ try {
69
+ host.chdir(previous.value);
70
+ } catch {}
71
+ })));
72
+ /**
73
+ * Applies `patch` to `env` and restores every patched key when the scope
74
+ * closes.
75
+ *
76
+ * @remarks
77
+ * An `undefined` value in `patch` deletes the key, and a key that was absent
78
+ * before is deleted again on restore. Assigning `undefined` to Node's
79
+ * `process.env` would store the string `"undefined"`, so neither direction
80
+ * ever assigns it.
81
+ */
82
+ static env = (env, patch) => Effect.asVoid(Effect.acquireRelease(Effect.sync(() => {
83
+ const saved = Object.keys(patch).map((key) => [key, Object.hasOwn(env, key) ? Option.fromUndefinedOr(env[key]) : Option.none()]);
84
+ for (const [key, value] of Object.entries(patch)) assign(env, key, value);
85
+ return saved;
86
+ }), (saved) => Effect.sync(() => {
87
+ for (const [key, value] of saved) assign(env, key, Option.getOrUndefined(value));
88
+ })));
89
+ };
90
+ const assign = (env, key, value) => {
91
+ if (value === void 0) delete env[key];
92
+ else env[key] = value;
93
+ };
94
+
95
+ export { ProcessScope, ProcessScopeError };
package/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { Context, Option, Schema } from "effect";
1
+ import { Context, Duration, Effect, Option, Schema, Scope } from "effect";
2
2
  /**
3
3
  * The carrier package a tool's bins were installed through.
4
4
  *
@@ -51,16 +51,190 @@ export declare const CurrentDistribution: Context.Reference<Option.Option<Distri
51
51
  */
52
52
  export declare const distributionSuffix: (distribution: Option.Option<Distribution>) => string;
53
53
  /**
54
- * The process-derived facts a front end resolves once, passed in as values.
54
+ * Decorates a `--version` line formatter so its line ends with
55
+ * {@link distributionSuffix}: `formatVersion(name, version)` followed by
56
+ * a space and `via <carrier> <version>` when installed through a carrier,
57
+ * unchanged for a direct install.
55
58
  *
56
59
  * @remarks
57
- * Nothing here reads `process`: `argv`, `env` and `cwd` come from the front
58
- * end's own `main.ts`. That keeps the resolution rule shared and testable
59
- * while the process read stays at the one place allowed to make it.
60
+ * Shaped around `effect/cli`'s `CliOutput.Formatter["formatVersion"]`: it
61
+ * wraps whatever formatter is in effect (a coloured default or a custom one)
62
+ * rather than replacing it. The suffix is computed once, when the decorator is
63
+ * applied, because the distribution is known at `main`. Data-last, for `pipe`.
64
+ *
65
+ * @example
66
+ * ```ts
67
+ * import { withDistributionVersion } from "@effected/engine";
68
+ * import { Option } from "effect";
69
+ *
70
+ * const formatVersion = withDistributionVersion(Option.some({ name: "@scope/plugin", version: "2.0.0" }))(
71
+ * (name, version) => `${name} ${version}`,
72
+ * );
73
+ * formatVersion("tool", "1.0.0"); // "tool 1.0.0 via @scope/plugin 2.0.0"
74
+ * ```
75
+ *
76
+ * @public
77
+ */
78
+ export declare const withDistributionVersion: (distribution: Option.Option<Distribution>) => ((formatVersion: (name: string, version: string) => string) => (name: string, version: string) => string);
79
+ /**
80
+ * Provides {@link CurrentDistribution} to `self`: `Option.some` of a carrier,
81
+ * `Option.none()` for `null` or `undefined` (a direct install).
82
+ *
83
+ * @remarks
84
+ * The one-line form of what a front end's `main` does once at the top of its
85
+ * program. Data-last, for `pipe`.
86
+ *
87
+ * @public
88
+ */
89
+ export declare const withDistribution: (distribution: Distribution | null | undefined) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
90
+ /**
91
+ * {@link Exclusive.run}'s required options.
92
+ *
93
+ * @public
94
+ */
95
+ interface ExclusiveRunOptions {
96
+ /**
97
+ * How long the body may run once it holds the permit. Required: a lane
98
+ * that mutates process-global state must not be held forever by a body
99
+ * that never settles. The timeout interrupts the body; it never releases
100
+ * the permit before the body's finalizers have run.
101
+ */
102
+ readonly timeout: Duration.Input;
103
+ }
104
+ /**
105
+ * {@link Exclusive.promise}'s options.
106
+ *
107
+ * @public
108
+ */
109
+ interface ExclusivePromiseOptions<A, E> {
110
+ /** Starts the promise. `signal` aborts when the effect is interrupted. */
111
+ readonly try: (signal: AbortSignal) => PromiseLike<A>;
112
+ /** Maps a rejection, or a synchronous throw from `try`, to the typed failure. */
113
+ readonly catch: (cause: unknown) => E;
114
+ /**
115
+ * On interruption, abort `signal` and resume at once instead of waiting for
116
+ * the promise to settle. Default `false` (abort, then wait). Set it for a
117
+ * promise that ignores its signal, which would otherwise hold the interrupt
118
+ * forever; see {@link Exclusive.promise}.
119
+ */
120
+ readonly abandon?: boolean;
121
+ }
122
+ declare const ExclusiveTimeout_base: Schema.Class<ExclusiveTimeout, Schema.TaggedStruct<"ExclusiveTimeout", {
123
+ readonly timeout: Schema.String;
124
+ readonly message: Schema.String;
125
+ }>, import("effect/Cause").YieldableError>;
126
+ /**
127
+ * The body of an {@link Exclusive.run} call ran past its timeout and was
128
+ * interrupted. Its finalizers had run, and the permit was released, by the
129
+ * time the caller sees this.
130
+ *
131
+ * @remarks
132
+ * Audience: calling code, which usually folds it into its own outcome (a tool
133
+ * result's `{ kind: "timeout" }`). `timeout` is the formatted duration.
134
+ *
135
+ * @public
136
+ */
137
+ export declare class ExclusiveTimeout extends ExclusiveTimeout_base {}
138
+ /**
139
+ * A one-permit lane for work that mutates process-global state (the working
140
+ * directory, the environment, a patched stream), so two requests never
141
+ * interleave it and the state is restored before the next one starts.
142
+ *
143
+ * @remarks
144
+ * Ordering, on every exit path:
145
+ *
146
+ * 1. Waiting for the permit is interruptible: a request cancelled while it is
147
+ * queued leaves the queue and never runs.
148
+ * 2. Once the permit is held, the caller's interruption is masked until the
149
+ * body ends. A transport that maps a client cancel to an interrupt (an MCP
150
+ * server does) only drops the response; the next request still waits for
151
+ * the real work to finish.
152
+ * 3. The required timeout interrupts the body, and only the body.
153
+ * 4. The body runs in its own `Scope`: its finalizers (restoring the working
154
+ * directory or the environment with {@link ProcessScope}, removing a temp
155
+ * directory) run, then the permit is released, then the caller sees the
156
+ * result, an {@link ExclusiveTimeout}, or its own deferred interruption.
157
+ *
158
+ * A body that ignores interruption delays its timeout and the permit release
159
+ * until it settles, as an uninterruptible region does. That is
160
+ * deliberate, because releasing the permit while process state is still being
161
+ * changed is the bug this lane exists to prevent. Run promise work through
162
+ * {@link Exclusive.promise}, whose interruption aborts the signal and then
163
+ * waits for the promise to settle; `Effect.promise` would abandon it. A
164
+ * promise that ignores its signal and never settles therefore hangs the
165
+ * timeout and the permit forever: give it `abandon: true`.
166
+ *
167
+ * **Not reentrant.** A `run` on the same lane from inside a body waits for the
168
+ * permit its own caller holds. It never gets it: the nested call waits until
169
+ * the outer timeout fires, which interrupts the body (and the nested wait with
170
+ * it), so the outer `run` fails with {@link ExclusiveTimeout}. Call the inner
171
+ * work directly instead of through the lane again.
172
+ *
173
+ * @example
174
+ * ```ts
175
+ * import { Exclusive, ProcessScope } from "@effected/engine"
176
+ * import { Effect } from "effect"
177
+ *
178
+ * const lane = yield* Exclusive.make
179
+ * const result = yield* lane.run(
180
+ * Effect.gen(function* () {
181
+ * yield* ProcessScope.chdir(process, root)
182
+ * return yield* Exclusive.promise({ try: (signal) => runTool(signal), catch: (cause) => new ToolFailed({ cause }) })
183
+ * }),
184
+ * { timeout: "2 minutes" },
185
+ * )
186
+ * ```
60
187
  *
61
188
  * @public
62
189
  */
63
- interface ProjectDirInput {
190
+ export declare class Exclusive {
191
+ private readonly semaphore;
192
+ private constructor();
193
+ /** A new lane with one permit. Bind it once (a module-level or layer-built value); every call shares it. */
194
+ static readonly make: Effect.Effect<Exclusive>;
195
+ /**
196
+ * A promise whose interruption aborts `signal` and then waits for the
197
+ * promise to settle, rather than abandoning it as `Effect.promise` and
198
+ * `Effect.tryPromise` do. A rejection, or a synchronous throw from `try`,
199
+ * fails through `catch`; a `catch` that itself throws dies with what it
200
+ * threw.
201
+ *
202
+ * @remarks
203
+ * **The default hangs on a promise that ignores its signal.** Waiting is
204
+ * the point: the interrupt (a lane timeout, a cancel) returns only once the
205
+ * promise has settled, so no work is still changing process state when the
206
+ * permit is released. But a promise that never observes `signal` and never
207
+ * settles (a test runner's `start`, a third-party call with no
208
+ * cancellation) holds the interrupt, the lane's timeout and the permit
209
+ * forever.
210
+ *
211
+ * Pass `abandon: true` for such a promise. Interruption still aborts
212
+ * `signal`, then resumes at once without waiting; the promise keeps running
213
+ * unobserved and its eventual result is dropped. Inside {@link Exclusive.run}
214
+ * the body's scope still closes, and its finalizers still run, before the
215
+ * permit is released. What abandoning gives up is the guarantee that the
216
+ * promise itself has stopped: choose it only when the promise cannot be
217
+ * stopped, and restore any state it touches in a finalizer.
218
+ */
219
+ static readonly promise: <A, E>(options: ExclusivePromiseOptions<A, E>) => Effect.Effect<A, E>;
220
+ /**
221
+ * Runs `body` holding this lane's permit, under the ordering in the class
222
+ * remarks. `body` gets its own `Scope`, closed before the permit is released.
223
+ */
224
+ readonly run: <A, E, R>(body: Effect.Effect<A, E, R>, options: ExclusiveRunOptions) => Effect.Effect<A, E | ExclusiveTimeout, Exclude<R, Scope.Scope>>;
225
+ }
226
+ /**
227
+ * The parameter shape {@link LaunchContext.resolve} takes: the process-derived
228
+ * facts a front end resolves once, passed in as values.
229
+ *
230
+ * @remarks
231
+ * Nothing here reads `process`: `argv` and `env` come from the front end's own
232
+ * `main.ts`. That keeps the resolution rule shared and testable while the
233
+ * process read stays at the one place allowed to make it.
234
+ *
235
+ * @public
236
+ */
237
+ interface ResolveInput {
64
238
  /**
65
239
  * Positional candidates, checked in order. Pass positional arguments only —
66
240
  * the parsed positionals of your command, never raw `process.argv.slice(2)`:
@@ -72,6 +246,14 @@ interface ProjectDirInput {
72
246
  readonly env: Readonly<Record<string, string | undefined>>;
73
247
  /** Env keys to try in order, for example `["OKFIT_PROJECT_DIR", "CLAUDE_PROJECT_DIR"]`. */
74
248
  readonly keys: ReadonlyArray<string>;
249
+ }
250
+ /**
251
+ * The parameter shape {@link LaunchContext.projectDir} takes: {@link ResolveInput}
252
+ * plus the `cwd` fallback.
253
+ *
254
+ * @public
255
+ */
256
+ interface ProjectDirInput extends ResolveInput {
75
257
  /** The fallback, usually `process.cwd()`. */
76
258
  readonly cwd: string;
77
259
  }
@@ -103,14 +285,117 @@ export declare class LaunchContext {
103
285
  * some launch paths; a path containing a placeholder is never what was meant.
104
286
  */
105
287
  static readonly isUnsubstituted: (value: string) => boolean;
288
+ /**
289
+ * `value` trimmed, when it names something: `Option.none()` for `undefined`,
290
+ * an empty or whitespace-only string, or a string still carrying a literal
291
+ * `${VAR}` placeholder ({@link LaunchContext.isUnsubstituted}).
292
+ *
293
+ * @remarks
294
+ * The guard every resolver here applies; use it directly for one positional
295
+ * argument, as in `LaunchContext.usable(argv[2])`. `??` would accept an empty
296
+ * string or a literal `${VAR}`, neither of which names a directory or an id.
297
+ */
298
+ static readonly usable: (value: string | undefined) => Option.Option<string>;
299
+ /**
300
+ * The first {@link LaunchContext.usable} `argv` value, then the first usable
301
+ * `env` value in `keys` order; `Option.none()` when none is usable.
302
+ *
303
+ * @remarks
304
+ * The resolver under {@link LaunchContext.projectDir}, without its `cwd`
305
+ * fallback, for any launch-supplied location: a host's plugin data
306
+ * directory, then an app override, with the caller's own fallback after
307
+ * it. Values are trimmed, so a value with surrounding whitespace resolves to
308
+ * the trimmed path.
309
+ *
310
+ * @example
311
+ * ```ts
312
+ * import { LaunchContext } from "@effected/engine"
313
+ * import { Option } from "effect"
314
+ *
315
+ * const dataDir = LaunchContext.resolve({ env, keys: ["CLAUDE_PLUGIN_DATA", "MYTOOL_DATA_DIR"] }).pipe(
316
+ * Option.getOrElse(() => `${home}/.mytool`),
317
+ * )
318
+ * ```
319
+ */
320
+ static readonly resolve: (input: ResolveInput) => Option.Option<string>;
106
321
  /**
107
322
  * The first usable argv value, then the first usable env value in `keys`
108
- * order, then `cwd`. A value is usable when it is non-empty after trimming
109
- * and carries no placeholder — `??` would return an empty string or a literal
110
- * `${VAR}`, neither of which names a directory.
323
+ * order, then `cwd`: {@link LaunchContext.resolve} with `cwd` as the
324
+ * fallback.
111
325
  */
112
326
  static readonly projectDir: (input: ProjectDirInput) => string;
113
327
  }
328
+ /**
329
+ * The working-directory half of a process, structurally. Node's `process`
330
+ * satisfies it; pass it in, so nothing here reads `process` itself.
331
+ *
332
+ * @public
333
+ */
334
+ interface ProcessCwdHost {
335
+ /** The current working directory. May throw when it was deleted (`ENOENT`). */
336
+ cwd(): string;
337
+ /** Changes the working directory. Throws when `directory` cannot be entered. */
338
+ chdir(directory: string): void;
339
+ }
340
+ declare const ProcessScopeError_base: Schema.Class<ProcessScopeError, Schema.TaggedStruct<"ProcessScopeError", {
341
+ readonly reason: Schema.Literal<"ChdirFailed">;
342
+ readonly path: Schema.String;
343
+ readonly message: Schema.String;
344
+ readonly cause: Schema.Defect;
345
+ }>, import("effect/Cause").YieldableError>;
346
+ /**
347
+ * A {@link ProcessScope} change could not be made.
348
+ *
349
+ * @remarks
350
+ * Audience: calling code (`reason`, `path`) and an end user (`message`).
351
+ * `"ChdirFailed"` means `chdir` threw for `path`; the original throw is
352
+ * `cause`. Nothing was changed, so nothing is restored.
353
+ *
354
+ * @public
355
+ */
356
+ export declare class ProcessScopeError extends ProcessScopeError_base {}
357
+ /**
358
+ * Scoped changes to process-global state, each restored when the enclosing
359
+ * `Scope` closes, on every exit path.
360
+ *
361
+ * @remarks
362
+ * Pair them with {@link Exclusive}: a scoped restore protects the next request
363
+ * only if no other request can run while the change is live.
364
+ *
365
+ * Both take the state they change as an argument (a {@link ProcessCwdHost},
366
+ * an environment record), so they read no `process` and test against plain
367
+ * doubles. For a temporary directory, use core's
368
+ * `FileSystem.makeTempDirectory` in an `Effect.acquireRelease` whose release
369
+ * ignores a failed removal; `makeTempDirectoryScoped`'s release dies on one,
370
+ * which turns a successful body into a defect.
371
+ *
372
+ * @public
373
+ */
374
+ export declare class ProcessScope {
375
+ private constructor();
376
+ /**
377
+ * Enters `directory` and returns to the previous working directory when the
378
+ * scope closes.
379
+ *
380
+ * @remarks
381
+ * When the previous directory cannot be read (it was deleted, so `cwd()`
382
+ * throws), the change still happens and nothing is restored: there is no
383
+ * valid directory to go back to. A restore that throws is ignored for the
384
+ * same reason.
385
+ */
386
+ static readonly chdir: (host: ProcessCwdHost, directory: string) => Effect.Effect<void, ProcessScopeError, Scope.Scope>;
387
+ /**
388
+ * Applies `patch` to `env` and restores every patched key when the scope
389
+ * closes.
390
+ *
391
+ * @remarks
392
+ * An `undefined` value in `patch` deletes the key, and a key that was absent
393
+ * before is deleted again on restore. Assigning `undefined` to Node's
394
+ * `process.env` would store the string `"undefined"`, so neither direction
395
+ * ever assigns it.
396
+ */
397
+ static readonly env: (env: Record<string, string | undefined>, patch: Readonly<Record<string, string | undefined>>) => Effect.Effect<void, never, Scope.Scope>;
398
+ }
114
399
  /**
115
400
  * What a caller — usually an agent — should do after a failure.
116
401
  *
@@ -145,5 +430,5 @@ export declare const Remediation: Schema.Struct<{
145
430
  * @public
146
431
  */
147
432
  export type Remediation = typeof Remediation.Type;
148
- export type { ProjectDirInput };
433
+ export type { ExclusivePromiseOptions, ExclusiveRunOptions, ProcessCwdHost, ProjectDirInput, ResolveInput };
149
434
  //# sourceMappingURL=index.d.ts.map
package/index.js CHANGED
@@ -1,5 +1,7 @@
1
- import { CurrentDistribution, Distribution, DistributionField, distributionSuffix } from "./Distribution.js";
1
+ import { CurrentDistribution, Distribution, DistributionField, distributionSuffix, withDistribution, withDistributionVersion } from "./Distribution.js";
2
+ import { Exclusive, ExclusiveTimeout } from "./Exclusive.js";
2
3
  import { LaunchContext } from "./LaunchContext.js";
4
+ import { ProcessScope, ProcessScopeError } from "./ProcessScope.js";
3
5
  import { Remediation } from "./Remediation.js";
4
6
 
5
- export { CurrentDistribution, Distribution, DistributionField, LaunchContext, Remediation, distributionSuffix };
7
+ export { CurrentDistribution, Distribution, DistributionField, Exclusive, ExclusiveTimeout, LaunchContext, ProcessScope, ProcessScopeError, Remediation, distributionSuffix, withDistribution, withDistributionVersion };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effected/engine",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "private": false,
5
5
  "description": "Platform-free primitives shared by every front end of an Effect v4 tool: distribution identity, remediation, launch context, and transport-neutral process crash guards",
6
6
  "keywords": [
@@ -5,7 +5,7 @@
5
5
  "toolPackages": [
6
6
  {
7
7
  "packageName": "@microsoft/api-extractor",
8
- "packageVersion": "7.59.1"
8
+ "packageVersion": "7.59.4"
9
9
  }
10
10
  ]
11
11
  }