@elaraai/create-e3 1.0.0

package/LICENSE.md

@@ -0,0 +1,51 @@
+Copyright (c) 2025 Elara AI Pty Ltd
+
+# East Workspace — Multi-License Repository
+
+This repository contains multiple components released under different
+licenses. Each component directory under `libs/` that contains its own
+`LICENSE.md` is governed **exclusively** by that file, which takes
+precedence over this one. This file licenses everything not otherwise
+covered, and summarizes the per-component split.
+
+## License by component
+
+- **Dual AGPL-3.0 / Commercial** — `east`, `east-node`, `east-ui`, and the
+  e3 SDK (`@elaraai/e3`, `@elaraai/e3-types`).
+- **Business Source License 1.1** — `east-c`, `east-py` (runtime, std, io,
+  cli), and the e3 server stack (`@elaraai/e3-core`, `@elaraai/e3-cli`,
+  `@elaraai/e3-api-client`, `@elaraai/e3-api-server`, `@elaraai/e3-api-tests`).
+- **Hybrid (TypeScript AGPL-3.0 / Python BSL 1.1)** — `east-py-datascience`.
+
+For the full terms of any component, see its `libs/<name>/LICENSE.md` and
+the per-package `LICENSE.md`.
+
+## Repository-level files
+
+All files that are **not** part of a component carrying its own
+`LICENSE.md` — including the build tooling, `scripts/`, `docs/`,
+`.github/`, the `Makefile`, and top-level configuration — are licensed
+under the GNU Affero General Public License v3.0 or later
+(AGPL-3.0-or-later).
+
+Full text: https://www.gnu.org/licenses/agpl-3.0.html
+
+## Commercial licensing
+
+To use any dual-licensed component without the source-disclosure
+requirements of AGPL-3.0, or to discuss licensing for Business Source
+License components, contact Elara AI Pty Ltd at support@elara.ai.
+
+## Contributions
+
+By submitting a contribution you agree to license it under the license(s)
+applicable to the component you are contributing to. See
+[CONTRIBUTING.md](CONTRIBUTING.md) and [CLA.md](CLA.md).
+
+## Governing Law
+
+This file is governed by the laws of New South Wales, Australia.
+
+---
+
+*Elara AI Pty Ltd*

package/dist/index.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+// ../scaffold-core/dist/scaffold.js
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+
+// ../scaffold-core/dist/names.js
+import { basename } from "node:path";
+function deriveNames(rawName, cwd) {
+  const source = rawName === "." ? basename(cwd) : rawName;
+  const projectName = source.trim().toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  if (projectName === "") {
+    throw new Error(`Could not derive a valid project name from "${rawName}"`);
+  }
+  const displayName = projectName.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+  const workspaceName = projectName.replace(/-/g, "_");
+  return { projectName, displayName, workspaceName };
+}
+
+// ../scaffold-core/dist/scaffold.js
+var TEXT_REPLACE_EXT = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".mjs",
+  ".json",
+  ".toml",
+  ".md",
+  ".txt",
+  ".yml",
+  ".yaml",
+  ".py",
+  ".nvmrc",
+  ".python-version",
+  ""
+]);
+var DOTFILE_RENAMES = {
+  gitignore: ".gitignore",
+  npmrc: ".npmrc"
+};
+function substituteTokens(content, names) {
+  return content.replaceAll("__PROJECT_NAME__", names.projectName).replaceAll("__DISPLAY_NAME__", names.displayName).replaceAll("__WORKSPACE_NAME__", names.workspaceName);
+}
+function transformPackageJson(raw, names, version) {
+  const pkg = JSON.parse(raw);
+  pkg.name = `@elaraai/${names.projectName}`;
+  pkg.description = names.displayName;
+  pkg.version = "0.0.1";
+  delete pkg.private;
+  const pin = `^${version}`;
+  for (const field of ["dependencies", "devDependencies", "peerDependencies"]) {
+    const deps = pkg[field];
+    if (!deps)
+      continue;
+    for (const [name, spec] of Object.entries(deps)) {
+      if (spec.startsWith("workspace:"))
+        deps[name] = pin;
+    }
+  }
+  return `${JSON.stringify(pkg, null, 2)}
+`;
+}
+function walk(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory())
+      out.push(...walk(full));
+    else
+      out.push(full);
+  }
+  return out;
+}
+function extOf(path) {
+  const base = path.slice(path.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot <= 0 ? "" : base.slice(dot);
+}
+function scaffold(options) {
+  const { kind, name, templateDir, version } = options;
+  const cwd = options.cwd ?? process.cwd();
+  const log = options.log ?? ((m) => console.log(m));
+  if (!existsSync(templateDir)) {
+    throw new Error(`Template directory not found: ${templateDir}`);
+  }
+  const names = deriveNames(name, cwd);
+  const inPlace = name === ".";
+  const projectDir = inPlace ? cwd : join(cwd, names.projectName);
+  if (!inPlace && existsSync(projectDir)) {
+    throw new Error(`Directory already exists: ${projectDir}`);
+  }
+  mkdirSync(projectDir, { recursive: true });
+  for (const srcPath of walk(templateDir)) {
+    const rel = relative(templateDir, srcPath);
+    const segments = rel.split(/[/\\]/);
+    const last = segments[segments.length - 1];
+    segments[segments.length - 1] = DOTFILE_RENAMES[last] ?? last;
+    const destRel = segments.join("/");
+    const destPath = join(projectDir, destRel);
+    mkdirSync(join(destPath, ".."), { recursive: true });
+    const baseName = segments[segments.length - 1];
+    if (baseName === "package.json") {
+      const manifest = transformPackageJson(readFileSync(srcPath, "utf8"), names, version);
+      writeFileSync(destPath, substituteTokens(manifest, names));
+    } else if (TEXT_REPLACE_EXT.has(extOf(srcPath)) || baseName.startsWith(".")) {
+      writeFileSync(destPath, substituteTokens(readFileSync(srcPath, "utf8"), names));
+    } else {
+      writeFileSync(destPath, readFileSync(srcPath));
+    }
+  }
+  log(`Created ${names.projectName} (${kind}) at ${projectDir}`);
+  if (options.install) {
+    runInstall(kind, projectDir, log);
+  }
+  return { ...names, projectDir, inPlace };
+}
+function hasCommand(cmd) {
+  const probe = process.platform === "win32" ? "where" : "which";
+  return spawnSync(probe, [cmd], { stdio: "ignore" }).status === 0;
+}
+function runInstall(kind, projectDir, log) {
+  log("Installing Node dependencies (npm install)...");
+  const npm = spawnSync("npm", ["install"], { cwd: projectDir, stdio: "inherit", shell: process.platform === "win32" });
+  if (npm.status !== 0) {
+    log("npm install failed \u2014 fix the issue and re-run `npm install`.");
+    return;
+  }
+  if (kind === "e3") {
+    if (hasCommand("uv")) {
+      log("Installing Python dependencies (uv sync)...");
+      const uv = spawnSync("uv", ["sync"], { cwd: projectDir, stdio: "inherit", shell: process.platform === "win32" });
+      if (uv.status !== 0)
+        log("uv sync failed \u2014 fix the issue and re-run `uv sync`.");
+    } else {
+      log("uv not found \u2014 install it (https://docs.astral.sh/uv/) then run `uv sync` to set up Python.");
+    }
+  }
+}
+
+// ../scaffold-core/dist/cli.js
+import { readFileSync as readFileSync2 } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+function runCreateCli(kind, moduleUrl) {
+  const pkgRoot = join2(dirname(fileURLToPath(moduleUrl)), "..");
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`Usage: npm create @elaraai/${kind} <project-name> [-- --install|--no-install]`);
+    console.log(`       create-${kind} <project-name|.> [--install|--no-install]`);
+    return;
+  }
+  const version = JSON.parse(readFileSync2(join2(pkgRoot, "package.json"), "utf8")).version;
+  const templateDir = join2(pkgRoot, "templates", kind);
+  const name = args.find((a) => !a.startsWith("-")) ?? ".";
+  const install = args.includes("--install") ? true : args.includes("--no-install") ? false : Boolean(process.stdout.isTTY);
+  try {
+    const result = scaffold({ kind, name, templateDir, version, install });
+    printNextSteps(kind, result.projectName, result.inPlace, install);
+  } catch (err) {
+    console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+function printNextSteps(kind, projectName, inPlace, installed) {
+  console.log("");
+  console.log("Next steps:");
+  if (!inPlace)
+    console.log(`  cd ${projectName}`);
+  if (!installed)
+    console.log(kind === "e3" ? "  npm run setup" : "  npm install");
+  console.log(kind === "e3" ? "  npm run start" : "  npm run test");
+}
+
+// src/index.ts
+runCreateCli("e3", import.meta.url);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@elaraai/create-e3",
+  "version": "1.0.0",
+  "description": "Scaffold a new e3 project (BSL-1.1, Node + Python, durable execution): npm create @elaraai/e3",
+  "type": "module",
+  "bin": {
+    "create-e3": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "license": "BSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elaraai/east-workspace.git",
+    "directory": "libs/create/packages/create-e3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "esbuild": "^0.24",
+    "typescript": "^5",
+    "@elaraai/scaffold-core": "1.0.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node --test \"dist/**/*.spec.js\""
+  }
+}

package/templates/e3/.nvmrc

@@ -0,0 +1 @@
+22

package/templates/e3/.python-version

@@ -0,0 +1 @@
+3.11

package/templates/e3/README.md

@@ -0,0 +1,26 @@
+# __DISPLAY_NAME__
+
+e3 project (BSL-1.1) — Node + Python, durable dataflow execution.
+
+## Setup
+
+```bash
+npm run setup     # npm install + uv sync (Node and Python deps)
+```
+
+## Commands
+
+```bash
+npm run build     # compile TypeScript
+npm run test      # build, export IR, run TS + Python tests
+npm run test:ts   # TypeScript tests only
+npm run test:py   # Python tests only (needs IR exported first)
+npm run deploy    # create repo (if needed) + deploy from ./src/index.ts
+npm run start     # deploy, then run the dataflow once
+npm run watch     # auto-deploy + run on every save
+npm run lint      # lint sources
+npm run clean     # remove build output, venv, repo, dependencies
+```
+
+The package is defined in `src/index.ts` as the default export; `npm run
+deploy`/`start`/`watch` deploy it straight from source via the e3 CLI.

package/templates/e3/eslint.config.js

@@ -0,0 +1,15 @@
+import tseslint from "@typescript-eslint/eslint-plugin";
+import tsparser from "@typescript-eslint/parser";
+
+export default [
+  { ignores: ["dist/", "node_modules/", ".venv/"] },
+  {
+    files: ["src/**/*.ts"],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: { ecmaVersion: "latest", sourceType: "module" },
+    },
+    plugins: { "@typescript-eslint": tseslint },
+    rules: {},
+  },
+];

package/templates/e3/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.venv/
+__pycache__/
+.repos/
+uv.lock

package/templates/e3/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@elaraai/template-e3",
+  "version": "0.0.0",
+  "private": true,
+  "description": "__DISPLAY_NAME__",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test:ts": "node --enable-source-maps --test \"dist/**/*.spec.js\"",
+    "test:export": "cross-env EXPORT_TEST_IR=dist/test-ir node --enable-source-maps --test \"dist/**/*.spec.js\"",
+    "test:py": "uv run pytest -v",
+    "test": "npm run build && npm run test:export && npm run test:py",
+    "setup": "npm install && uv sync",
+    "deploy": "e3 repo create .repos --exist-ok && e3 workspace deploy .repos __WORKSPACE_NAME__ --from-source ./src/index.ts",
+    "start": "npm run deploy && e3 dataflow run .repos __WORKSPACE_NAME__",
+    "watch": "e3 watch ./src/index.ts .repos __WORKSPACE_NAME__ --start",
+    "lint": "eslint .",
+    "clean": "rimraf dist node_modules .venv uv.lock .repos *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@elaraai/east": "workspace:*",
+    "@elaraai/east-node-std": "workspace:*",
+    "@elaraai/east-node-io": "workspace:*",
+    "@elaraai/east-py-datascience": "workspace:*",
+    "@elaraai/e3": "workspace:*",
+    "@elaraai/e3-types": "workspace:*"
+  },
+  "devDependencies": {
+    "@elaraai/e3-cli": "workspace:*",
+    "@types/node": "^22",
+    "typescript": "^5",
+    "eslint": "^9",
+    "@typescript-eslint/eslint-plugin": "^8",
+    "@typescript-eslint/parser": "^8",
+    "cross-env": "^7",
+    "rimraf": "^6"
+  },
+  "engines": { "node": ">=22" }
+}

package/templates/e3/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "__PROJECT_NAME__"
+description = "__DISPLAY_NAME__"
+requires-python = ">=3.11"
+version = "0.1.0"
+dependencies = [
+  "elaraai-east-py",
+  "elaraai-east-py-std",
+  "elaraai-east-py-io",
+  "elaraai-east-py-datascience",
+  "elaraai-east-py-cli",
+  "pytest",
+  "pytest-subtests",
+]

package/templates/e3/src/index.spec.ts

@@ -0,0 +1,15 @@
+import { East } from "@elaraai/east";
+import { describeEast, Assert } from "@elaraai/east-node-std";
+import { greetFn } from "./index.js";
+
+describeEast("__DISPLAY_NAME__", (test) => {
+  test("greet returns greeting message", ($) => {
+    const result = $.let(greetFn("World"));
+    $(Assert.equal(result, East.value("Hello, World!")));
+  });
+
+  test("greet with custom name", ($) => {
+    const result = $.let(greetFn("East"));
+    $(Assert.equal(result, East.value("Hello, East!")));
+  });
+}, { exportOnly: true });

package/templates/e3/src/index.ts

@@ -0,0 +1,14 @@
+import e3 from "@elaraai/e3";
+import { East, StringType } from "@elaraai/east";
+
+export const nameInput = e3.input("name", StringType, "World!");
+
+export const greetFn = East.function(
+  [StringType],
+  StringType,
+  ($, name) => East.str`Hello, ${name}!`,
+);
+
+export const greet = e3.task("greet", [nameInput], greetFn);
+
+export default e3.package("__PROJECT_NAME__", "1.0.0", greet);

package/templates/e3/tests/test_unit.py

@@ -0,0 +1,90 @@
+"""Run TypeScript-exported IR tests through the east-c Python bridge.
+
+Generate IR first:  npm run test:export
+Then run:           uv run pytest -v
+"""
+
+from pathlib import Path
+
+from east.runtime.compiler import compile_from_json
+from east.runtime.platform import PlatformFunction
+from east.runtime._compiler_eastc import _eastc_call
+from east.types.types import FunctionType, NullType, StringType
+
+try:
+    from east_py_std import platform as std_platform
+except ImportError:
+    std_platform = []
+
+try:
+    from east_py_io import platform as io_platform
+except ImportError:
+    io_platform = []
+
+TEST_IR_DIR = Path("dist/test-ir")
+
+
+def _get_ir_files():
+    if not TEST_IR_DIR.exists():
+        return []
+    return sorted(TEST_IR_DIR.glob("*.json"))
+
+
+def run_one(ir_file: Path) -> tuple[int, int]:
+    """Compile and run one IR test file. Returns (passed, failed)."""
+    data = ir_file.read_bytes()
+    is_async = b'"AsyncFunction"' in data[:100]
+
+    passed = 0
+    failed = 0
+
+    def describe_impl(name, test_fn):
+        if callable(test_fn):
+            try:
+                test_fn()
+            except Exception:
+                pass
+
+    def test_impl(name, test_fn):
+        nonlocal passed, failed
+        try:
+            if callable(test_fn):
+                test_fn()
+            passed += 1
+        except Exception:
+            failed += 1
+
+    def test_pass():
+        pass
+
+    def test_fail(msg):
+        raise AssertionError(msg)
+
+    test_names = {"describe", "test", "testPass", "testFail"}
+    platform = [
+        pf for pf in std_platform if pf["name"] not in test_names
+    ] + [
+        pf for pf in io_platform if pf["name"] not in test_names
+    ] + [
+        PlatformFunction(name="describe", inputs=[StringType, FunctionType([], NullType)], output=NullType, type="sync", fn=describe_impl),
+        PlatformFunction(name="test", inputs=[StringType, FunctionType([], NullType)], output=NullType, type="sync", fn=test_impl),
+        PlatformFunction(name="testPass", inputs=[], output=NullType, type="sync", fn=test_pass),
+        PlatformFunction(name="testFail", inputs=[StringType], output=NullType, type="sync", fn=test_fail),
+    ]
+
+    compiled = compile_from_json(data, platform, is_async=is_async)
+    handle = compiled._eastc_handle
+    _eastc_call(handle._compiled, handle._input_types, handle._output_type, ())
+    return passed, failed
+
+
+def pytest_generate_tests(metafunc):
+    if "ir_file" in metafunc.fixturenames:
+        files = _get_ir_files()
+        metafunc.parametrize("ir_file", files, ids=[f.stem for f in files])
+
+
+def test_ir(ir_file):
+    passed, failed = run_one(ir_file)
+    assert failed == 0, f"{failed} test(s) failed in {ir_file.stem}"
+    assert passed > 0, f"No tests ran in {ir_file.stem}"

package/templates/e3/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "exclude": ["dist"],
+  "compilerOptions": {
+    "outDir": "./dist",
+    "module": "nodenext",
+    "target": "esnext",
+    "lib": ["esnext", "es2024"],
+    "types": ["node"],
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+    "noErrorTruncation": true,
+    "incremental": true
+  }
+}