@elaraai/east-codex-plugin 0.0.0-stage → 1.0.89
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
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: east-project
|
|
3
|
+
description: "Create, initialise, and manage East / e3 projects end-to-end. Use when: (1) Scaffolding a new project ('create an e3 project called X', 'set up an East project', 'new East project'), (2) Choosing between an e3 project (BSL-1.1, Node + Python, durable execution) and an East project (AGPL-3.0, Node-only), (3) Driving the project lifecycle — install, build, deploy, run, watch, test — with the e3 CLI ('how do I run / deploy / watch / test this'), (4) Going from an empty directory to a running dataflow, (5) Splitting platform code into per-runtime workspace packages (--python-packages / --node-packages / --c-packages) for per-package change detection across Python, Node and C runners."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# East / e3 Project Lifecycle
|
|
7
|
+
|
|
8
|
+
Scaffold and run East projects. This skill creates the skeleton, then you implement the logic using the **e3**, **east**, **east-ui**, and **east-py-datascience** skills.
|
|
9
|
+
|
|
10
|
+
## Before writing code — search the example index
|
|
11
|
+
|
|
12
|
+
Every East API has a tested example in the plugin's index — the index IS the
|
|
13
|
+
API reference, printed from each example's IR in TypeScript or python. Before
|
|
14
|
+
writing or changing East code:
|
|
15
|
+
|
|
16
|
+
1. Call `search_east_examples` for each capability you
|
|
17
|
+
are about to use — `language: "python"` for east-py, `"typescript"`
|
|
18
|
+
otherwise. Summaries come back first: id, signature, the inputs and the
|
|
19
|
+
expected result, a few hundred bytes each.
|
|
20
|
+
2. Fetch the one or two that match with `get_east_example`
|
|
21
|
+
and pattern your code on them.
|
|
22
|
+
3. Do not read `node_modules/@elaraai/**` or `*.examples.ts` files wholesale,
|
|
23
|
+
and do not reason from `.d.ts` signatures: the index holds the same
|
|
24
|
+
programs, exact and far cheaper, and the signatures omit the runtime rules
|
|
25
|
+
that make East code correct.
|
|
26
|
+
|
|
27
|
+
Nothing is injected for you; the search is the step.
|
|
28
|
+
|
|
29
|
+
## Decision tree
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
Scaffolding an East project?
|
|
33
|
+
│
|
|
34
|
+
├─ Which kind?
|
|
35
|
+
│ ├─ Durable dataflow, workspaces, Python+Node+C → npm create @elaraai/e3 <name> (BSL-1.1)
|
|
36
|
+
│ └─ Plain East, Node platform fns only → npm create @elaraai/east <name> (AGPL-3.0)
|
|
37
|
+
│ └─ pass '.' for the current dir · add `-- --install` to install deps
|
|
38
|
+
│
|
|
39
|
+
├─ Need custom NATIVE functions?
|
|
40
|
+
│ ├─ One project-owned module (quick) → add `--platform` (TS-East, + a Python module while east-py is on — the default)
|
|
41
|
+
│ └─ Split into SEPARATE packages, each its own change-detection boundary:
|
|
42
|
+
│ ├─ Python (numpy / pandas / ML) → `--python-packages=pricing,forecasting` → packages/python/*
|
|
43
|
+
│ ├─ Node (TS / Node libraries) → `--node-packages=api` → packages/node/*
|
|
44
|
+
│ └─ C (native binary) → `--c-packages=solver` → packages/native/*
|
|
45
|
+
│
|
|
46
|
+
├─ Run it (e3) → npm run setup → npm run start (deploy + dataflow run; add `-v` for runner timing) → npm run watch
|
|
47
|
+
│ (an East project: npm install → npm run test)
|
|
48
|
+
│
|
|
49
|
+
└─ Move the @elaraai/* stack to a newer release → npm create @elaraai/e3@latest -- --update (e3-create skill)
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
| Kind | Command | License | Stack |
|
|
53
|
+
|---|---|---|---|
|
|
54
|
+
| **e3** | `npm create @elaraai/e3 <name>` | BSL-1.1 | Node + Python (+ C) |
|
|
55
|
+
| **East** | `npm create @elaraai/east <name>` | AGPL-3.0 | Node-only |
|
|
56
|
+
|
|
57
|
+
## Scaffold
|
|
58
|
+
|
|
59
|
+
Use the cross-platform `npm create` initializers (no plugin/PATH dependency, works on Windows/macOS/Linux):
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npm create @elaraai/e3 my-project # BSL-1.1, Node + Python, durable execution
|
|
63
|
+
npm create @elaraai/east my-project # AGPL-3.0, Node-only
|
|
64
|
+
# pass '.' instead of a name to scaffold into the current directory
|
|
65
|
+
# add `-- --install` to install dependencies as part of scaffolding
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
You get: `package.json`, `tsconfig.json`, `pyproject.toml` (e3 only), `src/index.ts` (a sample `e3.input` + `e3.task`, with the package as the default export), `src/index.spec.ts`, tests, and cross-platform npm scripts. Dependencies are pinned to the matching `@elaraai/*` release.
|
|
69
|
+
|
|
70
|
+
## Implement the logic
|
|
71
|
+
|
|
72
|
+
After scaffolding, edit `src/index.ts` to build the user's actual logic:
|
|
73
|
+
- Inputs and tasks → **e3** skill (`e3.input`, `e3.task`, `e3.package`, `e3.export`).
|
|
74
|
+
- East functions inside tasks → **east** skill.
|
|
75
|
+
- Decision surfaces / UI tasks → **east-ui** + **e3-ui** skills (`ui()`, `Data.bind`); screenshot them with **e3-ui-cli** (`npm run shot` in `--ui` scaffolds).
|
|
76
|
+
- ML / optimisation tasks → **east-py-datascience** skill.
|
|
77
|
+
|
|
78
|
+
## Project-owned platform modules (`--platform`)
|
|
79
|
+
|
|
80
|
+
When the project needs **its own** native functions, scaffold with `--platform`
|
|
81
|
+
(e3 only, opt-in). It **adapts to the chosen runners**: it always adds a TS-East
|
|
82
|
+
(east-node) platform module, and *additionally* a Python one when the east-py
|
|
83
|
+
runner is also selected — so a fresh project is ready to go with custom platforms
|
|
84
|
+
in whatever runtime(s) it has.
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
npm create @elaraai/e3 my-project -- --platform # TS-East, + Python (east-py is on by default)
|
|
88
|
+
npm create @elaraai/e3 my-project -- --platform --runners=east-node # TS-East only
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
**TS-East half (always, runnable after `npm install`):** a `src/platform/`
|
|
92
|
+
directory whose `index.ts` barrel is the package's **scoped** `./platform`
|
|
93
|
+
subpath export (a `PlatformFunction[]`).
|
|
94
|
+
- `src/platform/example.ts` — an example fn with declaration **and**
|
|
95
|
+
`.implement(...)` co-located. The example task runs it on
|
|
96
|
+
`{ runtime: "east-node", platforms: [{ custom: "@elaraai/<project>" }] }` — the
|
|
97
|
+
custom name is the package's full scoped name so east-node-cli self-resolves
|
|
98
|
+
the `./platform` export.
|
|
99
|
+
- **Add another:** drop `src/platform/<fn>.ts` (exporting its declaration +
|
|
100
|
+
`<fn>Impl`), then in `src/platform/index.ts` import `<fn>Impl`, re-export the
|
|
101
|
+
`<fn>` declaration, and add `<fn>Impl` to the default-exported array.
|
|
102
|
+
|
|
103
|
+
**Python half (added only when east-py is on, runnable after `uv sync`):** a
|
|
104
|
+
`platform_module/` package whose `__init__.py` is a thin **aggregator**.
|
|
105
|
+
- `platform_module/example.py` — an example `@East.platform_function` ending with
|
|
106
|
+
`<name>_impl = platform_functions(__name__)`; `__init__.py` spreads it into the
|
|
107
|
+
top-level `platform` list `east-py run -p platform_module` loads. This mirrors
|
|
108
|
+
the first-party east-py-std / east-py-datascience packages. A setuptools
|
|
109
|
+
`[build-system]` block plus `[tool.setuptools] packages = ["platform_module"]`
|
|
110
|
+
makes the package importable from the project's `.venv` (re-run `uv sync` after
|
|
111
|
+
adding native deps like numpy to `pyproject.toml`).
|
|
112
|
+
- `src/platform_module.ts` — a hand-written `East.platform(name, inputs, output)`
|
|
113
|
+
**declaration** mirroring the Python signature (no codegen — keep the two in
|
|
114
|
+
lockstep). The example task runs it on
|
|
115
|
+
`{ runtime: "east-py", platforms: [{ custom: "platform_module" }, "east-py-std"] }`.
|
|
116
|
+
- **Add another:** drop `platform_module/<fn>.py` (ending `<fn>_impl =
|
|
117
|
+
platform_functions(__name__)`), import + spread it in `__init__.py`, and add the
|
|
118
|
+
matching `East.platform(...)` declaration to `src/platform_module.ts`.
|
|
119
|
+
|
|
120
|
+
Conventions: platform-function names are **dotted `"<project>.<fn>"`** (an opaque
|
|
121
|
+
binding string, frozen into the content-addressed `taskHash` on publish — so it
|
|
122
|
+
must be the scaffold default). The bare typed runner resolves the runner binary
|
|
123
|
+
from the project's own `.venv` / `node_modules` — **no `uv run` wrapper, no
|
|
124
|
+
`project` field**. The scaffolded example functions are named generically
|
|
125
|
+
(`example_python`, `exampleNode`) — replace them with your own.
|
|
126
|
+
|
|
127
|
+
**Adding this to an EXISTING project** (no `--platform` scaffold): create
|
|
128
|
+
`src/platform/index.ts` (default-export the `PlatformFunction[]`); add the
|
|
129
|
+
subpath to `package.json` `exports` — `"./platform": "./dist/platform/index.js"`
|
|
130
|
+
(keep `"."` too); the e3 task's `{ custom: "@elaraai/<name>" }` must equal the
|
|
131
|
+
package.json `name` exactly; and ensure the project is **built** before
|
|
132
|
+
`e3 dataflow run` (the scaffold's `start` runs `npm run build` first). For the
|
|
133
|
+
Python half, add the setuptools `[build-system]` + `[tool.setuptools] packages`
|
|
134
|
+
to `pyproject.toml` and `uv sync`.
|
|
135
|
+
|
|
136
|
+
## Multi-package projects (per-runner change granularity)
|
|
137
|
+
|
|
138
|
+
Split platform code into separate workspace packages — each its own captured
|
|
139
|
+
execution environment, so editing one re-runs only its tasks (the rest stay
|
|
140
|
+
cached, even across a redeploy). Scaffold with `--python-packages` /
|
|
141
|
+
`--node-packages` / `--c-packages`; the **e3-create** skill is the full
|
|
142
|
+
reference — every flag, the generated layout, and the per-runtime task wiring
|
|
143
|
+
(python & node auto-derive the environment from `{ custom }`; C attaches a
|
|
144
|
+
prebuilt binary via `environment: { tools }`). Every python and node member
|
|
145
|
+
also ships an East function (`functions.py` / `functions.ts`, listed in its
|
|
146
|
+
`east_functions` / `eastFunctions`) that the app calls through
|
|
147
|
+
`East.importFunction` — the other way across the language boundary: East IR
|
|
148
|
+
authored in the package's language, exported and embedded by `e3.export`
|
|
149
|
+
itself, run by the default runner with nothing installed where it runs (the
|
|
150
|
+
**e3** skill).
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
## Lifecycle (generated npm scripts)
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
npm run setup # e3: npm install + uv sync (npm install alone without east-py); an East project has none — npm install
|
|
157
|
+
npm run build # tsc (after the npm workspace members, in a multi-package project)
|
|
158
|
+
npm run test # e3: build + export IR + TS (+ Python) tests; east: build + TS tests
|
|
159
|
+
npm run deploy # e3: repo create (--exist-ok) + workspace deploy --from-source
|
|
160
|
+
npm run start # e3: deploy, then dataflow run
|
|
161
|
+
npm run watch # e3: e3 watch ./src/index.ts .repos <ws> --start (live reload)
|
|
162
|
+
npm run shot # e3 --ui scaffolds: render src/ui/index.tsx to surface.png (e3-ui-cli)
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Under the hood the e3 scripts use the e3 CLI's source-deploy:
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
e3 repo create .repos --exist-ok
|
|
169
|
+
e3 workspace deploy .repos <ws> --from-source ./src/index.ts # bundle + import + create ws + deploy
|
|
170
|
+
e3 dataflow run .repos <ws> # add -v for per-runner timing/perf (in `e3 task logs`)
|
|
171
|
+
e3 dataset get .repos <ws>.<name> # read a result (flat path)
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## Typical flow for "create an e3 project called X that does Y"
|
|
175
|
+
|
|
176
|
+
1. `npm create @elaraai/e3 X`
|
|
177
|
+
2. `cd X`
|
|
178
|
+
3. Edit `src/index.ts`: define inputs + tasks implementing **Y** (use the e3/east skills).
|
|
179
|
+
4. `npm run setup && npm run start` (or `npm run watch` for iteration).
|
|
180
|
+
5. `e3 dataset get .repos <ws>.<task>` to read outputs.
|
|
181
|
+
|
|
182
|
+
## Related skills
|
|
183
|
+
|
|
184
|
+
- **e3-create** — the full `npm create @elaraai/{e3,east}` flag reference (every option + its effect, single vs multi-package layouts). This skill picks up *after* scaffolding.
|
|
185
|
+
- **e3** — the SDK + CLI this builds on.
|
|
186
|
+
- **east** — the language for task bodies.
|
|
187
|
+
- **east-ui** / **e3-ui** — decision surfaces.
|
|
188
|
+
- **e3-ui-cli** — screenshot a scaffolded surface (`npm run shot`, `e3-ui doctor`).
|
|
189
|
+
- **east-py-datascience** — ML/optimisation tasks.
|