@effected/engine 0.1.0 → 0.3.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/LaunchContext.js CHANGED
@@ -2,6 +2,19 @@
2
2
  /**
3
3
  * Resolves where a tool launched by an agent host should treat as its project.
4
4
  *
5
+ * @example
6
+ * ```ts
7
+ * import { LaunchContext } from "@effected/engine"
8
+ *
9
+ * const dir = LaunchContext.projectDir({
10
+ * argv: [],
11
+ * env: { CLAUDE_PROJECT_DIR: "/work/app" },
12
+ * keys: ["MYTOOL_PROJECT_DIR", "CLAUDE_PROJECT_DIR"],
13
+ * cwd: "/home/me",
14
+ * })
15
+ * // => "/work/app"
16
+ * ```
17
+ *
5
18
  * @public
6
19
  */
7
20
  var LaunchContext = class LaunchContext {
@@ -10,8 +23,8 @@ var LaunchContext = class LaunchContext {
10
23
  * Whether a value still carries a literal `${VAR}` placeholder.
11
24
  *
12
25
  * @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.
26
+ * An agent host can pass `${CLAUDE_PROJECT_DIR}` through unsubstituted in
27
+ * some launch paths; a path containing a placeholder is never what was meant.
15
28
  */
16
29
  static isUnsubstituted = (value) => {
17
30
  const open = value.indexOf("${");
@@ -21,7 +34,7 @@ var LaunchContext = class LaunchContext {
21
34
  * The first usable argv value, then the first usable env value in `keys`
22
35
  * order, then `cwd`. A value is usable when it is non-empty after trimming
23
36
  * and carries no placeholder — `??` would return an empty string or a literal
24
- * `${VAR}`, which is the bug this replaces.
37
+ * `${VAR}`, neither of which names a directory.
25
38
  */
26
39
  static projectDir = (input) => {
27
40
  const usable = (value) => {
package/README.md CHANGED
@@ -7,10 +7,10 @@
7
7
 
8
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
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
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
14
  > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
15
15
  >
16
16
  > **Stability: unstable.** This package's API surface is not yet considered
package/Remediation.js CHANGED
@@ -5,11 +5,22 @@ import { Schema } from "effect";
5
5
  * What a caller — usually an agent — should do after a failure.
6
6
  *
7
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.
8
+ * `hint` is the human-readable instruction. `suggestedTool` and `suggestedArgs`
9
+ * optionally name the tool to call next and the arguments to call it with, so
10
+ * an agent can act without parsing the hint. The optional keys are
11
+ * `optionalKey`: omit them rather than passing an explicit `undefined`, which
12
+ * is rejected instead of silently encoded.
13
+ *
14
+ * @example
15
+ * ```ts
16
+ * import { Remediation } from "@effected/engine"
17
+ *
18
+ * const remediation: Remediation = {
19
+ * hint: "Run the validator on the whole bundle first.",
20
+ * suggestedTool: "validate_bundle",
21
+ * suggestedArgs: { strict: true },
22
+ * }
23
+ * ```
13
24
  *
14
25
  * @public
15
26
  */
package/index.d.ts CHANGED
@@ -81,6 +81,19 @@ interface ProjectDirInput {
81
81
  /**
82
82
  * Resolves where a tool launched by an agent host should treat as its project.
83
83
  *
84
+ * @example
85
+ * ```ts
86
+ * import { LaunchContext } from "@effected/engine"
87
+ *
88
+ * const dir = LaunchContext.projectDir({
89
+ * argv: [],
90
+ * env: { CLAUDE_PROJECT_DIR: "/work/app" },
91
+ * keys: ["MYTOOL_PROJECT_DIR", "CLAUDE_PROJECT_DIR"],
92
+ * cwd: "/home/me",
93
+ * })
94
+ * // => "/work/app"
95
+ * ```
96
+ *
84
97
  * @public
85
98
  */
86
99
  export declare class LaunchContext {
@@ -89,15 +102,15 @@ export declare class LaunchContext {
89
102
  * Whether a value still carries a literal `${VAR}` placeholder.
90
103
  *
91
104
  * @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.
105
+ * An agent host can pass `${CLAUDE_PROJECT_DIR}` through unsubstituted in
106
+ * some launch paths; a path containing a placeholder is never what was meant.
94
107
  */
95
108
  static readonly isUnsubstituted: (value: string) => boolean;
96
109
  /**
97
110
  * The first usable argv value, then the first usable env value in `keys`
98
111
  * order, then `cwd`. A value is usable when it is non-empty after trimming
99
112
  * and carries no placeholder — `??` would return an empty string or a literal
100
- * `${VAR}`, which is the bug this replaces.
113
+ * `${VAR}`, neither of which names a directory.
101
114
  */
102
115
  static readonly projectDir: (input: ProjectDirInput) => string;
103
116
  }
@@ -107,11 +120,22 @@ export declare class LaunchContext {
107
120
  * What a caller — usually an agent — should do after a failure.
108
121
  *
109
122
  * @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.
123
+ * `hint` is the human-readable instruction. `suggestedTool` and `suggestedArgs`
124
+ * optionally name the tool to call next and the arguments to call it with, so
125
+ * an agent can act without parsing the hint. The optional keys are
126
+ * `optionalKey`: omit them rather than passing an explicit `undefined`, which
127
+ * is rejected instead of silently encoded.
128
+ *
129
+ * @example
130
+ * ```ts
131
+ * import { Remediation } from "@effected/engine"
132
+ *
133
+ * const remediation: Remediation = {
134
+ * hint: "Run the validator on the whole bundle first.",
135
+ * suggestedTool: "validate_bundle",
136
+ * suggestedArgs: { strict: true },
137
+ * }
138
+ * ```
115
139
  *
116
140
  * @public
117
141
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effected/engine",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "private": false,
5
5
  "description": "Platform-free primitives shared by every front end of an Effect v4 tool: distribution identity, remediation, and launch context",
6
6
  "keywords": [
@@ -37,7 +37,7 @@
37
37
  "./package.json": "./package.json"
38
38
  },
39
39
  "peerDependencies": {
40
- "effect": "4.0.0-rc.117"
40
+ "effect": "^4.0.0"
41
41
  },
42
42
  "engines": {
43
43
  "node": ">=24.11.0"