@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 +42 -2
- package/Exclusive.js +141 -0
- package/LaunchContext.js +48 -15
- package/ProcessScope.js +95 -0
- package/index.d.ts +295 -10
- package/index.js +4 -2
- package/package.json +1 -1
- package/tsdoc-metadata.json +1 -1
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
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
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
|
|
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
|
|
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
|
|
77
|
+
const found = LaunchContext.usable(input.env[key]);
|
|
78
|
+
if (Option.isSome(found)) return found;
|
|
52
79
|
}
|
|
53
|
-
return
|
|
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 };
|
package/ProcessScope.js
ADDED
|
@@ -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
|
-
*
|
|
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
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
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
|
-
|
|
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
|
|
109
|
-
*
|
|
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.
|
|
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": [
|