@elaraai/east-codex-plugin 0.0.0-stage → 1.0.90
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/.build/daemon/east-py-lsp.js +568 -0
- package/.build/daemon/lsp.js +3737 -0
- package/.build/daemon/server.js +3535 -0
- package/.build/hooks/codex-tools.js +584 -0
- package/.build/hooks/diagnose-bash.js +399 -0
- package/.build/hooks/diagnose.js +347 -0
- package/.build/hooks/pre-read.js +100 -0
- package/.build/hooks/pre-write.js +247 -0
- package/.build/hooks/session-start.js +263 -0
- package/.build/hooks/subagent-start.js +212 -0
- package/.build/mcp/server.js +23577 -0
- package/.build/status/report.js +2163 -0
- package/.codex-plugin/plugin.json +36 -0
- package/.lsp.json +21 -0
- package/.mcp.json +11 -0
- package/LICENSE.md +682 -0
- package/README.md +192 -2
- package/hooks/hooks.json +51 -0
- package/index.json +44926 -0
- package/package.json +36 -4
- package/skills/e3/SKILL.md +841 -0
- package/skills/e3-create/SKILL.md +265 -0
- package/skills/e3-ui/SKILL.md +2260 -0
- package/skills/e3-ui-cli/SKILL.md +332 -0
- package/skills/east/SKILL.md +690 -0
- package/skills/east-contribute/SKILL.md +348 -0
- package/skills/east-design/SKILL.md +233 -0
- package/skills/east-node-io/SKILL.md +143 -0
- package/skills/east-node-std/SKILL.md +289 -0
- package/skills/east-ontology/SKILL.md +181 -0
- package/skills/east-project/SKILL.md +189 -0
- package/skills/east-py/SKILL.md +2023 -0
- package/skills/east-py-datascience/SKILL.md +280 -0
- package/skills/east-py-io/SKILL.md +186 -0
- package/skills/east-py-std/SKILL.md +301 -0
- package/skills/east-ui/SKILL.md +1529 -0
package/README.md
CHANGED
|
@@ -1,3 +1,193 @@
|
|
|
1
|
-
#
|
|
1
|
+
# East Plugin for Codex
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The East programming language ecosystem for Codex: all 16 skills, tested example search, project detection, search-before-coding hooks, preemptive diagnostics, and both TypeScript/TSX and Python language servers.
|
|
4
|
+
|
|
5
|
+
The implementation is shared with the Claude Code plugin in [`../east-plugin`](../east-plugin). The plugin ships as the npm package `@elaraai/east-codex-plugin`, assembled at build time from this directory's manifests and bundles, the shared skills (adapted for Codex) and the example index — self-contained: installing it does **not** require a local clone, pnpm, a build, or a sibling `east-plugin` directory.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
Requires **Node.js 22+ on PATH** and a Codex client with `codex plugin` and lifecycle hooks. Python diagnostics additionally use your project's east-py installation; TypeScript diagnostics use your project's TypeScript and East dependencies.
|
|
10
|
+
|
|
11
|
+
### From the published catalog (no local clone)
|
|
12
|
+
|
|
13
|
+
The public catalog [elaraai/plugins](https://github.com/elaraai/plugins) is a Codex marketplace (`.agents/plugins/marketplace.json`, named `elaraai-codex`) whose entry is the npm package, pinned at the released version:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
codex plugin marketplace add elaraai/plugins
|
|
17
|
+
codex plugin add east-codex-plugin@elaraai-codex
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Codex fetches the package from npm and installs it as it is. You do not need to clone or build the East repositories yourself. The monorepo root keeps a marketplace of the same name whose entry points at the same package, so an install added as `elaraai/east-workspace` keeps updating. Pre-releases are the catalog's `beta` branch (`codex plugin marketplace add elaraai/plugins --ref beta`, named `elaraai-codex-beta`).
|
|
21
|
+
|
|
22
|
+
Start a **new Codex thread**. Open `/hooks` in the Codex CLI and review/trust the East hooks. Codex discovers `hooks/hooks.json`, but installation alone does not trust its commands. If your configuration disables hooks, enable them with `codex --enable hooks` (or `[features] hooks = true` in your Codex config).
|
|
23
|
+
|
|
24
|
+
Ask Codex to call `east_status`, then `search_east_examples` with `query: "array map"`. The status checks shipped artifacts, all skills, the index and project runtime prerequisites; `/hooks` shows whether hooks are actually trusted and active. Inspect MCP availability with `/mcp`.
|
|
25
|
+
|
|
26
|
+
**Updating the GitHub install:**
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
codex plugin marketplace upgrade elaraai-codex
|
|
30
|
+
codex plugin remove east-codex-plugin@elaraai-codex
|
|
31
|
+
codex plugin add east-codex-plugin@elaraai-codex
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Start a new thread and review any changed hooks in `/hooks`.
|
|
35
|
+
|
|
36
|
+
### From a local checkout (development)
|
|
37
|
+
|
|
38
|
+
A checkout is a local marketplace once the plugin is assembled: `make -C libs/east-codex-plugin build` (or `make build` at the root) bundles the host and writes the plugin, with the marketplace files that name it, under `libs/east-plugin/marketplace/`, under the catalog's name `elaraai-codex` (one name registers once: adding the checkout points it there, adding `elaraai/plugins` points it back):
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
cd ~/src/east-workspace
|
|
42
|
+
make -C libs/east-codex-plugin build # shared runtime + host build + bundles → ../east-plugin/marketplace/east-codex-plugin/
|
|
43
|
+
codex plugin marketplace add ~/src/east-workspace/libs/east-plugin/marketplace
|
|
44
|
+
codex plugin add east-codex-plugin@elaraai-codex
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Start a new thread and review/trust the East hooks in `/hooks`. `codex plugin marketplace list` shows the configured sources.
|
|
48
|
+
|
|
49
|
+
**Iterating on the plugin:** installed plugins run from a cached copy. After editing source, rebuild as above, then reinstall to refresh the cache:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
codex plugin remove east-codex-plugin@elaraai-codex
|
|
53
|
+
codex plugin add east-codex-plugin@elaraai-codex
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
This rebuild assumes your monorepo development dependencies are already installed and built, as for the Claude plugin. If examples changed, regenerate the index as described below before rebuilding.
|
|
57
|
+
|
|
58
|
+
Removing and reinstalling clears the old cache even when the manifest version has not changed. **Start a new thread**, then review changed hooks in `/hooks`. `marketplace upgrade` refreshes Git snapshots; use the remove/add cycle above for local source changes.
|
|
59
|
+
|
|
60
|
+
Both host packages declare `"@elaraai/east-plugin": "workspace:*"` in `package.json`. pnpm links the shared library during development, just like other monorepo dependencies. Bundling includes that library in each plugin's shipped JavaScript, so the assembled plugin runs independently of the workspace: that directory is what the release publishes as `@elaraai/east-codex-plugin` (see [`../east-plugin`](../east-plugin#publishing)).
|
|
61
|
+
|
|
62
|
+
If shared behavior changed, test both host plugins:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pnpm --filter '@elaraai/east-claude-plugin' test
|
|
66
|
+
pnpm --filter '@elaraai/east-codex-plugin' test
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Regenerating examples
|
|
70
|
+
|
|
71
|
+
If you changed the example corpus, build its dependencies and regenerate the shared index before bundling:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
cd ~/src/east-workspace
|
|
75
|
+
make -C libs/east build
|
|
76
|
+
make -C libs/east-node build
|
|
77
|
+
pnpm --filter '@elaraai/east-py-datascience' run build
|
|
78
|
+
(cd libs/east-py && uv sync --all-packages)
|
|
79
|
+
pnpm --filter '@elaraai/east-plugin' run generate-index
|
|
80
|
+
make -C libs/east-codex-plugin build
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The generator imports built example modules and uses east-py's printer through `uv`. It updates `libs/east-plugin/index.json`, the one committed artifact — commit it alongside the examples (CI's `plugin-artifacts` fails when it is stale). Nothing else generated is committed: the bundles, the adapted skills and the assembled plugin are build outputs.
|
|
84
|
+
|
|
85
|
+
## Skills
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
| Skill | Package | Description |
|
|
89
|
+
|-------|---------|-------------|
|
|
90
|
+
| `east` | `@elaraai/east` | Core East language - types, expressions, compilation |
|
|
91
|
+
| `east-node-std` | `@elaraai/east-node-std` | Node.js platform functions (Console, FileSystem, Fetch, Crypto, Random, Time) |
|
|
92
|
+
| `east-node-io` | `@elaraai/east-node-io` | I/O platform functions (SQL, NoSQL, S3, FTP, XLSX, compression) |
|
|
93
|
+
| `east-py` | `elaraai-east-py` | Python runtime - East expressions and East values as plain data, eager methods, @East.platform_function |
|
|
94
|
+
| `east-py-std` | `elaraai-east-py-std` | Standard platform functions on the Python runtime (direct `*_impl` calls) |
|
|
95
|
+
| `east-py-io` | `elaraai-east-py-io` | I/O platform functions on the Python runtime (direct `*_impl` calls) |
|
|
96
|
+
| `east-py-datascience` | `@elaraai/east-py-datascience` | Data science & ML (MADS, Optuna, XGBoost, Torch, GP, SHAP, Causal) |
|
|
97
|
+
| `east-ui` | `@elaraai/east-ui` | UI components (50+ typed components for layouts, forms, charts) |
|
|
98
|
+
| `e3` | `@elaraai/e3` | East Execution Engine - durable execution for East pipelines |
|
|
99
|
+
| `e3-ui` | `@elaraai/e3-ui` | e3 + UI bridge - reactive decision surfaces as e3 tasks (Data.bind, ui(), Diff, Ontology) |
|
|
100
|
+
| `e3-ui-cli` | `@elaraai/e3-ui-cli` | Render east-ui / e3-ui components to PNG/HTML (`e3-ui shot`), managed headless Chromium, server setup (`install-browser`, `doctor`) |
|
|
101
|
+
| `east-project` | _(plugin-native)_ | Create + manage East/e3 projects — scaffolds via `east-scaffold`, drives the build/deploy/run lifecycle |
|
|
102
|
+
| `east-design` | _(plugin-native)_ | Architect a solution before coding — discovery questions, capability→skill mapping, example searches, design doc |
|
|
103
|
+
| `east-ontology` | _(plugin-native)_ | Build an Economic Ontology of a business and render it with the e3-ui Ontology editor — elicitation methodology, node/link model, `OntologyType` encoding |
|
|
104
|
+
| `east-contribute` | _(plugin-native)_ | Contribute a change to the monorepo from a GitHub issue — triage → lib(s)/skills, anti-duplication discovery, East diagnostics + examples↔tests contract, build/test/lint + CI gates, issue → branch → PR |
|
|
105
|
+
| `e3-create` | `@elaraai/create-e3` | Scaffold e3 solutions and project templates |
|
|
106
|
+
|
|
107
|
+
Invoke a skill with `$east-codex-plugin:<skill-name>` or select it from Codex's skill picker. For example, use `east-design` to design a solution and `east-project` to scaffold and run it.
|
|
108
|
+
|
|
109
|
+
The single editable skill catalog is `../east-plugin/skills/`; package-owned skills there are symlinks to their owning libraries. **Edit the source.** `package` (run by `build`) dereferences every skill and adapts Claude-specific tool names and invocation syntax for Codex into the assembled plugin. Nothing in the installed skill set depends on a symlink outside the plugin.
|
|
110
|
+
|
|
111
|
+
## Example Search (MCP)
|
|
112
|
+
|
|
113
|
+
The legacy `.mcp.json` launcher sets `cwd: "."` (resolved by Codex relative to the installed plugin) and passes `./.build/mcp/server.js` to Node. Codex 0.154.0 passes these MCP arguments literally; `${PLUGIN_ROOT}` is available to hook commands but is not expanded in legacy MCP arguments. Keep the explicit working directory so startup works from any project directory.
|
|
114
|
+
|
|
115
|
+
- **`search_east_examples(query, language, format, limit, package)`**: ranked summaries of tested East programs; request `format: "full"` for code.
|
|
116
|
+
- **`get_east_example(id, language)`**: one complete example from a search result.
|
|
117
|
+
- **`east_status(directory)`**: installed artifacts and project readiness.
|
|
118
|
+
- **`east_lsp_diagnostics(file, timeout_ms, refresh)`**: diagnostics from either real language server, selected by file extension.
|
|
119
|
+
|
|
120
|
+
Program examples are stored as IR with TypeScript and Python renderings; JSX UI examples are TypeScript-only. Search before writing East code, fetch the relevant example, and follow its tested pattern. Do not learn East runtime rules by sweeping `.d.ts` or `*.examples.ts` files.
|
|
121
|
+
|
|
122
|
+
## Hooks and Diagnostics
|
|
123
|
+
|
|
124
|
+
| Capability | Codex integration |
|
|
125
|
+
|---|---|
|
|
126
|
+
| Project detection, skill guidance, diagnostics warmup | `SessionStart` |
|
|
127
|
+
| Guidance for subagents | `SubagentStart` |
|
|
128
|
+
| Search-before-coding reminder or refusal | `PreToolUse` for `apply_patch`, edits and recognized shell writes |
|
|
129
|
+
| Reminder when sweeping declarations/examples | `PreToolUse` for shell reads/searches and file read/search tools |
|
|
130
|
+
| File diagnostics | `PostToolUse` for patches, file reads/edits and recognized shell reads/writes |
|
|
131
|
+
| Session search tracking | `PostToolUse` for East example-search MCP tools |
|
|
132
|
+
| TypeScript/TSX language server | `.build/daemon/lsp.js`, reachable through MCP |
|
|
133
|
+
| Python language server | `.build/daemon/east-py-lsp.js`, reachable through MCP |
|
|
134
|
+
|
|
135
|
+
The default search gate adds guidance. Set `EAST_REQUIRE_SEARCH=deny` in the environment inherited by Codex to refuse an East write until a search is recorded. Tracking uses MCP hook events and a transcript fallback; it does not require a stable Codex transcript format.
|
|
136
|
+
|
|
137
|
+
Codex's documented plugin schema does not register `lspServers` natively. Both real LSP executables are included, with their stdio launch configuration in `.lsp.json` for compatible clients. The MCP bridge starts them on demand and keeps connections warm. Automatic post-edit reviews run through hooks using the same shared diagnostic rules, rather than depending on native LSP registration.
|
|
138
|
+
|
|
139
|
+
Call `east_lsp_diagnostics` with an absolute `.ts`, `.tsx` or `.py` path. It sends `initialize`, `didOpen`/`didChange` and `didSave` as appropriate and returns a diagnostic publication. Python's build tier can publish later: call again with `refresh: false` to retrieve the latest publication without restarting analysis. An empty publication can mean a file is outside the server's scope; a timeout is not a clean result. Use `east_status` to check runtime readiness.
|
|
140
|
+
|
|
141
|
+
TypeScript reviews use the shared warm diagnostics daemon and `@elaraai/east-diagnostics` rules. Python uses the project's own `east-py lsp`, with its existing lint fallback; `[tool.east-py] check = true` enables the opted-in build tier. Install east-py in the project's environment or set `EAST_PY_LINT` to its executable. Review blocks are deduplicated by session, path and file contents.
|
|
142
|
+
|
|
143
|
+
Shell path detection covers ordinary reads, redirects, heredocs, `tee`, `sed -i`, copies and moves. Dynamically computed paths, arbitrary scripts and hosted tool operations may not be visible to hooks; request explicit LSP diagnostics for those files. Hook coverage is not an enforcement boundary.
|
|
144
|
+
|
|
145
|
+
See the official [plugin packaging](https://developers.openai.com/plugins/build/plugins) and [hook documentation](https://learn.chatgpt.com/docs/hooks) for discovery, trust and tool event formats.
|
|
146
|
+
|
|
147
|
+
## Project Scaffolding
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
npm create @elaraai/east my-project
|
|
151
|
+
npm create @elaraai/e3 my-project
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
East projects include Node.js platform functions; e3 projects add durable execution and Python/data-science integrations. See [`../create`](../create) for project templates.
|
|
155
|
+
|
|
156
|
+
## Local CLI Installation
|
|
157
|
+
|
|
158
|
+
Install the East CLIs without maintaining a source checkout:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
curl -fsSL https://raw.githubusercontent.com/elaraai/east-workspace/main/libs/east-plugin/scripts/install.sh | bash
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
This installs npm/PyPI tools; east-c is built from a temporary source checkout by the script. It is separate from installing the Codex plugin.
|
|
165
|
+
|
|
166
|
+
For contributors who want the complete monorepo cloned and built:
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
curl -fsSL https://raw.githubusercontent.com/elaraai/east-workspace/main/libs/east-plugin/scripts/install-dev.sh | bash
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
| Shared script | Purpose |
|
|
173
|
+
|---|---|
|
|
174
|
+
| `install.sh` | Install `east-node`, `e3`, `east-py`, and `east-c` |
|
|
175
|
+
| `install-dev.sh` | Clone the monorepo, install, build and link CLIs |
|
|
176
|
+
| `update.sh` | Update installed CLIs |
|
|
177
|
+
| `update-dev.sh` | Pull and rebuild the source workspace |
|
|
178
|
+
|
|
179
|
+
The `scripts/` shell entry points in this plugin delegate to those shared scripts.
|
|
180
|
+
|
|
181
|
+
## Testing
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
pnpm --filter '@elaraai/east-plugin' test
|
|
185
|
+
pnpm --filter '@elaraai/east-codex-plugin' test
|
|
186
|
+
pnpm --filter '@elaraai/east-claude-plugin' test
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Tests cover patch parsing, search gating, shell reads, automatic diagnostics, every skill, and MCP + real LSP startup from an isolated installed copy with no plugin `node_modules` or sibling repositories — all over the assembled plugin, the thing that ships. CI also checks that the committed index remains current and that both plugins assemble.
|
|
190
|
+
|
|
191
|
+
## Contributing and License
|
|
192
|
+
|
|
193
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md), [CLA.md](CLA.md), and [LICENSE.md](LICENSE.md). East is dual-licensed under AGPL-3.0 and commercial licenses. [Elara AI](https://elaraai.com/).
|
package/hooks/hooks.json
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
{
|
|
2
|
+
"description": "East plugin hooks: project detection, the search-before-coding gate, and preemptive diagnostics (files edited, read, or written through the shell)",
|
|
3
|
+
"hooks": {
|
|
4
|
+
"SessionStart": [
|
|
5
|
+
{
|
|
6
|
+
"hooks": [
|
|
7
|
+
{
|
|
8
|
+
"type": "command",
|
|
9
|
+
"command": "node \"${PLUGIN_ROOT}/.build/hooks/session-start.js\"",
|
|
10
|
+
"timeout": 5
|
|
11
|
+
}
|
|
12
|
+
]
|
|
13
|
+
}
|
|
14
|
+
],
|
|
15
|
+
"SubagentStart": [
|
|
16
|
+
{
|
|
17
|
+
"hooks": [
|
|
18
|
+
{
|
|
19
|
+
"type": "command",
|
|
20
|
+
"command": "node \"${PLUGIN_ROOT}/.build/hooks/subagent-start.js\"",
|
|
21
|
+
"timeout": 5
|
|
22
|
+
}
|
|
23
|
+
]
|
|
24
|
+
}
|
|
25
|
+
],
|
|
26
|
+
"PreToolUse": [
|
|
27
|
+
{
|
|
28
|
+
"matcher": "apply_patch|Bash|exec_command|shell_command|Read|Edit|Write|Grep|Glob|mcp__.*__(?:search_east_examples|get_east_example)$",
|
|
29
|
+
"hooks": [
|
|
30
|
+
{
|
|
31
|
+
"type": "command",
|
|
32
|
+
"command": "node \"${PLUGIN_ROOT}/.build/hooks/codex-tools.js\"",
|
|
33
|
+
"timeout": 30
|
|
34
|
+
}
|
|
35
|
+
]
|
|
36
|
+
}
|
|
37
|
+
],
|
|
38
|
+
"PostToolUse": [
|
|
39
|
+
{
|
|
40
|
+
"matcher": "apply_patch|Bash|exec_command|shell_command|Read|Edit|Write|Grep|Glob|mcp__.*__(?:search_east_examples|get_east_example)$",
|
|
41
|
+
"hooks": [
|
|
42
|
+
{
|
|
43
|
+
"type": "command",
|
|
44
|
+
"command": "node \"${PLUGIN_ROOT}/.build/hooks/codex-tools.js\"",
|
|
45
|
+
"timeout": 30
|
|
46
|
+
}
|
|
47
|
+
]
|
|
48
|
+
}
|
|
49
|
+
]
|
|
50
|
+
}
|
|
51
|
+
}
|