@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.
@@ -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.