@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,265 @@
1
+ ---
2
+ name: e3-create
3
+ description: "Scaffold East / e3 projects with the `npm create @elaraai/e3` and `npm create @elaraai/east` initializers. Use when: (1) Creating a new project from scratch ('create an e3 project', 'set up an East project', 'new project called X'), (2) Choosing e3 (durable dataflow, Node+Python+C) vs east (Node-only), (3) Deciding CLI flags — --runners, --platform, --python-packages / --node-packages / --c-packages, --ui, --tests, --eslint, --install — and understanding exactly what each generates, (4) Splitting platform code into per-runtime workspace packages for per-package change detection. After scaffolding, the east-project skill drives the build/deploy/run/watch lifecycle."
4
+ ---
5
+
6
+ # e3-create — scaffolding East / e3 projects
7
+
8
+ The `npm create @elaraai/{e3,east}` initializers (package `libs/create`:
9
+ `create-e3`, `create-east`, `scaffold-core`) turn an empty directory into a
10
+ buildable project. This skill is the **flag reference**: which initializer,
11
+ which flags, and exactly what each one generates. Implementing the logic and
12
+ running the lifecycle is the **east-project** skill; the SDK/API is **e3**.
13
+
14
+ ## Before writing code — search the example index
15
+
16
+ Every East API has a tested example in the plugin's index — the index IS the
17
+ API reference, printed from each example's IR in TypeScript or python. Before
18
+ writing or changing East code:
19
+
20
+ 1. Call `search_east_examples` for each capability you
21
+ are about to use — `language: "python"` for east-py, `"typescript"`
22
+ otherwise. Summaries come back first: id, signature, the inputs and the
23
+ expected result, a few hundred bytes each.
24
+ 2. Fetch the one or two that match with `get_east_example`
25
+ and pattern your code on them.
26
+ 3. Do not read `node_modules/@elaraai/**` or `*.examples.ts` files wholesale,
27
+ and do not reason from `.d.ts` signatures: the index holds the same
28
+ programs, exact and far cheaper, and the signatures omit the runtime rules
29
+ that make East code correct.
30
+
31
+ Nothing is injected for you; the search is the step.
32
+
33
+ ## Decision tree
34
+
35
+ ```
36
+ Scaffolding a project?
37
+ │
38
+ ├─ Which initializer?
39
+ │ ├─ Durable dataflow, workspaces, Python+Node+C runners → npm create @elaraai/e3 <name> (BSL-1.1)
40
+ │ └─ Plain East programs, Node platform fns only → npm create @elaraai/east <name> (AGPL-3.0)
41
+ │ └─ <name> = dir to create · `.` = current dir (default) · `-- --install` to install deps
42
+ │
43
+ ├─ Which runtimes? (e3) → --runners=east-node,east-py,east-c (default: all three)
44
+ │
45
+ ├─ Custom NATIVE functions?
46
+ │ ├─ One project-owned module → --platform (TS-East; + Python when east-py is on)
47
+ │ └─ Split into SEPARATE packages (per-package change detection — supersedes --platform):
48
+ │ ├─ Python (numpy/pandas/ML) → --python-packages=pricing,forecasting → packages/python/* (uv members)
49
+ │ ├─ Node (TS/Node libs) → --node-packages=api → packages/node/* (npm members)
50
+ │ └─ C (native binary) → --c-packages=solver → packages/native/* (tools env)
51
+ │
52
+ ├─ Extras (e3) → --ui (east-ui+e3-ui) · --tests (default on) · --eslint (on) · --editor-diagnostics (on)
53
+ │
54
+ ├─ Then → cd <name> → e3: npm run setup → npm run start · east: npm install → npm run test (lifecycle: east-project skill)
55
+ │
56
+ └─ Bump an EXISTING project's @elaraai/* stack → npm create @elaraai/e3@<version> -- --update (run inside the project)
57
+ ```
58
+
59
+ | Initializer | License | Stack | Default export |
60
+ |---|---|---|---|
61
+ | `npm create @elaraai/e3 <name>` | BSL-1.1 | Node + Python (+ C) | an `e3.package(...)` |
62
+ | `npm create @elaraai/east <name>` | AGPL-3.0 | Node-only | an East program |
63
+
64
+ ## Invocation
65
+
66
+ ```bash
67
+ npm create @elaraai/e3 my-app # interactive when a TTY (prompts for features)
68
+ npm create @elaraai/e3 my-app -- --no-ui --runners=east-node,east-py # flags after `--`
69
+ npm create @elaraai/e3 . # scaffold into the CURRENT directory
70
+ create-e3 my-app --ui # the bin directly (no `npm create`, no `--`)
71
+ npm create @elaraai/e3 -- --help # full flag list
72
+ npm create @elaraai/e3@latest -- --update # inside a project: move every @elaraai/* dependency to that version
73
+ ```
74
+
75
+ - The **project name** is the first non-`-` argument; omit it (or pass `.`) to scaffold into the current directory.
76
+ - Under `npm create`, flags go **after `--`** (npm forwards them). The `create-e3` / `create-east` bins take flags directly.
77
+ - A run is **interactive** only when stdin and stdout are a TTY **and** no selection flag is passed. The selection flags are `--tests`/`--no-tests`, `--ui`/`--no-ui`, `--platform`/`--no-platform`, `--eslint`/`--no-eslint`, `--runners=…` and the `--*-packages` flags — any one makes the run non-interactive (safe for CI and pipes). `--install`/`--no-install` and `--editor-diagnostics` do not.
78
+ - **`--update`** (either initializer, inside an existing project) scaffolds nothing: it rewrites every `@elaraai/*` dependency to the initializer's own version — the lockstep stack version, so `@latest` for the newest — and drops the stale lock so the install resolves without an `ERESOLVE`. `--install`/`--no-install` apply as for a scaffold.
79
+
80
+ ## CLI flags — and exactly what each does
81
+
82
+ **Both `e3` and `east`:**
83
+
84
+ | Flag | Default | Effect |
85
+ |---|---|---|
86
+ | `--install` / `--no-install` | install when TTY | Run `npm install` (+ `uv sync` for e3) after scaffolding (or `--update`). |
87
+ | `--update` | — | Bump an existing project's `@elaraai/*` stack to this initializer's version, instead of scaffolding. |
88
+ | `--eslint` / `--no-eslint` | on | Add ESLint wired with `@elaraai/eslint-plugin-east` (the East lint rules). |
89
+ | `--editor-diagnostics` / `--no-editor-diagnostics` | on | Add `@elaraai/tsserver-plugin-east` to `tsconfig.json` (editor squiggles for East idioms). TypeScript only — the python diagnostics need no flag: `elaraai-east-py-cli` brings `east-py lint` / `check` / `lsp` plus flake8 and pylsp plugins, configured by the generated `[tool.east-py]`. |
90
+
91
+ **`e3` only:**
92
+
93
+ | Flag | Default | Effect |
94
+ |---|---|---|
95
+ | `--runners=<list>` | all | Comma list of `east-node,east-py,east-c` to include. Prunes the unused runtimes' setup: east-node and east-c bring their CLI dev dependency (`@elaraai/east-node-cli`, `@elaraai/east-c-cli`); east-py brings `pyproject.toml`, `.python-version`, `tests/test_unit.py` and `@elaraai/east-py-datascience`. |
96
+ | `--tests` / `--no-tests` | on | Emit `src/index.spec.ts` (+ Python tests when east-py is on). |
97
+ | `--ui` / `--no-ui` | off | Add `east-ui` + `e3-ui`, a `src/ui/index.tsx` surface, and the screenshot scripts (`npm run shot`, `shots:png`, `shots:html` — e3-ui-cli). |
98
+ | `--platform` / `--no-platform` | off | Add ONE project-owned platform module (see below). Ignored when any `--*-packages` is given. |
99
+ | `--python-packages=<list>` | — | uv workspace members under `packages/python/*`. Implies `--runners` east-py. |
100
+ | `--node-packages=<list>` | — | npm workspace members under `packages/node/*`. Implies east-node. |
101
+ | `--c-packages=<list>` | — | Native binaries under `packages/native/*`, wired via a `tools` env. Implies east-c. |
102
+
103
+ **Interactions to know:**
104
+ - Each `--<runtime>-packages` **implies its runner** (a package can't run without it), applied *after* `--runners=` so a contradictory `--runners` can't disable a needed runtime.
105
+ - Any `--<runtime>-packages` sets `--platform` **off** — the generated packages ARE the platform path (they replace the single-file demo).
106
+ - Package names must be **unique across all runtimes** (each becomes a distinct `src/packages/<name>.ts` task) and follow the runtime's packaging rules: python `[a-z][a-z0-9_]*` (import-safe), node `[a-z][a-z0-9-]*`, C `[a-z][a-z0-9_-]*`. A name that collides with a real registry package should be renamed.
107
+ - `create-east` has no `--tests` (its spec is always generated) and none of the e3-only flags.
108
+
109
+ ## What you get (single project, no package flags)
110
+
111
+ ```
112
+ my-app/
113
+ ├── package.json # @elaraai/* pinned; cross-platform npm scripts (setup/build/test/deploy/start/watch)
114
+ ├── tsconfig.json # + tsserver-plugin-east (unless --no-editor-diagnostics)
115
+ ├── pyproject.toml # e3 + east-py runner only; `[tool.east-py]` configures diagnostics (`check` opts into the build tier)
116
+ ├── eslint.config.js # unless --no-eslint
117
+ └── src/
118
+ ├── index.ts # a sample e3.input + e3.task; the e3.package is the default export
119
+ └── index.spec.ts # unless --no-tests
120
+ ```
121
+
122
+ `--ui` adds `src/ui/index.tsx` (a `ui()` surface from `@elaraai/e3-ui`) + `npm run shot`.
123
+
124
+ ## Custom platform functions
125
+
126
+ **`--platform` (one project-owned module).** Adds a TS-East platform module
127
+ (`src/platform/`, exported as the package's `./platform` subpath) and — when
128
+ east-py is also selected — a Python one (`platform_module/` + a mirrored
129
+ `East.platform(...)` declaration in `src/platform_module.ts`). The example task
130
+ runs on `{ runtime: "east-node", platforms: [{ custom: "@elaraai/<project>" }] }`
131
+ (or the east-py equivalent). Good for a single project-local native function.
132
+
133
+ **`--python-packages` / `--node-packages` / `--c-packages` (multi-package).**
134
+ Split platform code into **separate workspace packages, each its own captured
135
+ execution environment** — so editing one package re-runs only its tasks, the
136
+ rest stay cached (even across a redeploy). The package boundary *is* the
137
+ change-detection granularity. Mix runtimes freely:
138
+
139
+ ```bash
140
+ npm create @elaraai/e3 my-app -- \
141
+ --python-packages=pricing --node-packages=api --c-packages=solver
142
+ ```
143
+
144
+ ```
145
+ my-app/
146
+ ├── package.json # npm workspace root: workspaces ["packages/node/*"], private
147
+ ├── pyproject.toml # uv workspace root: members ["packages/python/*"]
148
+ ├── tsconfig.json # excludes "packages" (members compile themselves)
149
+ ├── src/
150
+ │ ├── index.ts # e3.package("my-app", "1.0.0", ...packageTasks)
151
+ │ └── packages/
152
+ │ ├── index.ts # barrel: export const packageTasks = [...pricing_tasks, ...api_tasks, ...solver_tasks]
153
+ │ └── pricing.ts · api.ts · solver.ts # the example tasks of each package (below)
154
+ └── packages/
155
+ ├── python/pricing/ # uv member — pyproject.toml (hatchling) + src/pricing/{__init__,example,functions}.py
156
+ ├── node/api/ # npm member — package.json (@my-app/api, ./platform + ./functions exports) + src/{platform,functions}.ts
157
+ └── native/solver/ # native — Makefile + src/solver.c → build/solver
158
+ ```
159
+
160
+ **Every python and node member crosses the language boundary BOTH ways, and the
161
+ task wiring differs by runtime — a PLATFORM function (native code; python & node
162
+ AUTO-DERIVE the environment from the `{ custom }` platform reference) and an EAST
163
+ function the package exports (imported with `East.importFunction`, embedded at
164
+ export, run by the DEFAULT runner: no runner, platform or environment); C
165
+ attaches a prebuilt binary explicitly:**
166
+
167
+ ```typescript
168
+ // Three separate files under src/packages/. Each begins with:
169
+ // import e3 from "@elaraai/e3";
170
+ // import { East, ArrayType, FloatType, IntegerType, FunctionType, variant } from "@elaraai/east";
171
+
172
+ // ── src/packages/pricing.ts — PYTHON ──
173
+ // 1. the platform function (native python; env AUTO-DERIVED from { custom: "pricing" })
174
+ const example = East.platform("pricing.example", [ArrayType(FloatType)], FloatType);
175
+ // 2. the East function authored in python (src/pricing/functions.py, listed in `east_functions`)
176
+ const scale = East.importFunction("pricing", "scale",
177
+ FunctionType([ArrayType(FloatType), FloatType], ArrayType(FloatType)));
178
+ const values = e3.input("pricing_values", ArrayType(FloatType), variant("value", [1.0, 2.0, 3.0]));
179
+ const factor = e3.input("pricing_factor", FloatType, variant("value", 2.0));
180
+ export const pricing_task = e3.task("pricing_example", [values],
181
+ East.function([ArrayType(FloatType)], FloatType, ($, v) => { $.return(example(v)); }),
182
+ { runner: { runtime: "east-py", platforms: [{ custom: "pricing" }, "east-py-std"] } });
183
+ // no `environment:` — export captures packages/python/pricing's uv closure
184
+ export const pricing_scaled_task = e3.task("pricing_scaled", [values, factor],
185
+ East.function([ArrayType(FloatType), FloatType], ArrayType(FloatType), ($, v, f) => { $.return(scale(v, f)); }));
186
+ // no runner at all — e3.export exports `pricing`'s east_functions (east-py export-functions) and embeds the IR
187
+ export const pricing_tasks = [pricing_task, pricing_scaled_task];
188
+
189
+ // ── src/packages/api.ts — NODE (the member's SCOPED npm name) ──
190
+ const example = East.platform("api.example", [IntegerType, FloatType], IntegerType);
191
+ const scale = East.importFunction("@my-app/api", "scale",
192
+ FunctionType([ArrayType(FloatType), FloatType], ArrayType(FloatType))); // src/functions.ts, in `eastFunctions`
193
+ const value = e3.input("api_value", IntegerType, variant("value", 21n));
194
+ const factor = e3.input("api_factor", FloatType, variant("value", 2.0));
195
+ const series = e3.input("api_series", ArrayType(FloatType), variant("value", [1.0, 2.0, 3.0]));
196
+ export const api_task = e3.task("api_example", [value, factor],
197
+ East.function([IntegerType, FloatType], IntegerType, ($, v, f) => { $.return(example(v, f)); }),
198
+ { runner: { runtime: "east-node", platforms: [{ custom: "@my-app/api" }] } });
199
+ // no `environment:` — export captures packages/node/api's npm closure
200
+ export const api_scaled_task = e3.task("api_scaled", [series, factor],
201
+ East.function([ArrayType(FloatType), FloatType], ArrayType(FloatType), ($, s, f) => { $.return(scale(s, f)); }));
202
+ // e3.export exports the BUILT ./functions entry (east-node export-functions) and embeds the IR
203
+ export const api_tasks = [api_task, api_scaled_task];
204
+
205
+ // ── src/packages/solver.ts — C (NOT auto-derived; attach the built binary via tools) ──
206
+ const solverValues = e3.input("solver_values", ArrayType(FloatType), variant("value", [1.0, 2.0, 3.0]));
207
+ export const solver_task = e3.customTask("solver_tool", [solverValues], ArrayType(FloatType),
208
+ (_$, inputs, output) => East.str`solver ${inputs.get(0n)} ${output}`,
209
+ { environment: { tools: { files: ["packages/native/solver/build/solver"] } } });
210
+ // build the C binary first: `make -C packages/native/solver` — a rebuild re-runs only this task
211
+ export const solver_tasks = [solver_task];
212
+ ```
213
+
214
+ The member side holds both crossings. The platform impl is keyed to the same
215
+ dotted `"<pkg>.example"` name: `packages/python/pricing/src/pricing/example.py`
216
+ is an `@East.platform_function`; `packages/node/api/src/platform.ts` is
217
+ `East.platform(...).implement(...)` default-exported as a `PlatformFunction[]`.
218
+ Keep the member impl and the app-side `East.platform(...)` declaration in
219
+ lockstep (same name + signature). The East function is
220
+ `packages/python/pricing/src/pricing/functions.py` (an east-py `East.function`,
221
+ listed in the root module's `east_functions = {"scale": scale}`) and
222
+ `packages/node/api/src/functions.ts` (`export const eastFunctions = { scale }`,
223
+ the package's `./functions` export) — East all the way down, so the app's
224
+ `FunctionType` must equal the exported type exactly (e3 checks it at export)
225
+ and the task runs anywhere, with no python or Node package where it runs. To
226
+ add one, build it and list it under the name the app imports; e3 finds the
227
+ member in the uv / npm workspace and exports it itself (the **e3** skill).
228
+
229
+ **Build order / semantics.** Python members install the workspace's full locked
230
+ third-party set (union-scoped); node members must be `tsc`-built before export
231
+ (the root `build` runs `--workspaces` first — both the `./platform` and the
232
+ `./functions` entries are read from `dist/`); C tools must be `make`-built
233
+ before `npm run start`. Add more packages later with the same flags — each new
234
+ one is captured independently.
235
+
236
+ ## Worked examples
237
+
238
+ ```bash
239
+ # Node + Python, no UI, install now
240
+ npm create @elaraai/e3 planner -- --runners=east-node,east-py --no-ui --install
241
+
242
+ # Python-only ML project, one python package for the model
243
+ npm create @elaraai/e3 forecaster -- --runners=east-py --python-packages=model
244
+
245
+ # Everything: three runtimes, one package each, UI on
246
+ npm create @elaraai/e3 demo -- --python-packages=pricing --node-packages=api --c-packages=solver --ui
247
+
248
+ # A plain East (Node-only) program, without ESLint
249
+ npm create @elaraai/east mylib -- --no-eslint
250
+ ```
251
+
252
+ ## After scaffolding
253
+
254
+ The generated `npm` scripts (`setup`, `build`, `test`, `deploy`, `start`,
255
+ `watch`, `shot`) and the deploy/run flow are the **east-project** skill. Add
256
+ `-v` to `npm run start`'s dataflow run for per-runner timing in the task logs.
257
+
258
+ ## Related skills
259
+
260
+ - **east-project** — the lifecycle after scaffolding: implement, build, deploy, run, watch, test.
261
+ - **e3** — the SDK (`e3.input` / `e3.task` / `e3.package` / `e3.export`) + CLI the generated code uses; per-package environment auto-derivation and self-resolving `East.importFunction` imports.
262
+ - **east** — the language for task bodies and `East.platform(...)` declarations.
263
+ - **east-py** — author the `@East.platform_function` and the `East.function` a `--python-packages` member exports; **east-node-std** — the east-node platform fn a `--node-packages` member exports; **east** — its `East.function` and the app's `East.importFunction`.
264
+ - **east-ui** / **e3-ui** / **e3-ui-cli** — the `--ui` surface and screenshotting it (`npm run shot`).
265
+ - **east-design** — start here when you have a goal but no architecture yet.