@elaraai/create-e3 1.0.30 → 1.0.31

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/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 { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, statSync as statSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join2, relative as relative2 } from "node:path";
 import { spawnSync } from "node:child_process";
 
 // ../scaffold-core/dist/names.js
@@ -18,6 +18,203 @@ function deriveNames(rawName, cwd) {
   return { projectName, displayName, workspaceName };
 }
 
+// ../scaffold-core/dist/packages.js
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+var RUNTIMES = {
+  // Python package/dir names must be import-safe (letters, digits, underscore).
+  python: {
+    runtime: "python",
+    destParent: "packages/python",
+    templateName: "python",
+    label: "Python",
+    valid: /^[a-z][a-z0-9_]*$/,
+    rule: "lowercase letters, digits and underscores, starting with a letter"
+  },
+  // Node member names become the last segment of an npm dir; keep them tame.
+  node: {
+    runtime: "node",
+    destParent: "packages/node",
+    templateName: "node",
+    label: "Node",
+    valid: /^[a-z][a-z0-9-]*$/,
+    rule: "lowercase letters, digits and hyphens, starting with a letter"
+  },
+  // C build dir names — letters, digits, underscore, hyphen.
+  c: {
+    runtime: "c",
+    destParent: "packages/native",
+    templateName: "c",
+    label: "C",
+    valid: /^[a-z][a-z0-9_-]*$/,
+    rule: "lowercase letters, digits, underscores and hyphens, starting with a letter"
+  }
+};
+var RUNTIME_ORDER = ["python", "node", "c"];
+function toIdent(name) {
+  return name.replace(/[^a-zA-Z0-9]/g, "_");
+}
+function substitute(text, names, version, pkg) {
+  let out = text.replaceAll("__PROJECT_NAME__", names.projectName).replaceAll("__DISPLAY_NAME__", names.displayName).replaceAll("__WORKSPACE_NAME__", names.workspaceName).replaceAll("__VERSION__", version);
+  if (pkg)
+    out = out.replaceAll("__PACKAGE_NAME__", pkg.name).replaceAll("__PACKAGE_IDENT__", pkg.ident);
+  return out;
+}
+function walkFiles(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory())
+      out.push(...walkFiles(full));
+    else
+      out.push(full);
+  }
+  return out;
+}
+function stampMember(projectDir, templateRoot, cfg, names, version, pkg) {
+  const memberTemplate = join(templateRoot, cfg.templateName);
+  if (!existsSync(memberTemplate)) {
+    throw new Error(`internal: missing package template for ${cfg.label} at ${memberTemplate}`);
+  }
+  const memberDir = join(projectDir, cfg.destParent, pkg.name);
+  for (const srcPath of walkFiles(memberTemplate)) {
+    const rel = relative(memberTemplate, srcPath).replaceAll("\\", "/");
+    if (!rel.includes("/") && rel.startsWith("_")) {
+      if (rel === "_app.ts") {
+        const dest2 = join(projectDir, "src", "packages", `${pkg.name}.ts`);
+        mkdirSync(join(dest2, ".."), { recursive: true });
+        writeFileSync(dest2, substitute(readFileSync(srcPath, "utf8"), names, version, pkg));
+      }
+      continue;
+    }
+    const dest = join(memberDir, substitute(rel, names, version, pkg));
+    mkdirSync(join(dest, ".."), { recursive: true });
+    writeFileSync(dest, substitute(readFileSync(srcPath, "utf8"), names, version, pkg));
+  }
+}
+function writePythonWorkspaceRoot(projectDir, names, members) {
+  const sources = members.map((m) => `${m} = { workspace = true }`).join("\n");
+  const body = `[project]
+name = "${names.projectName}"
+version = "0.1.0"
+description = "${names.displayName}"
+requires-python = ">=3.11"
+dependencies = [
+  "elaraai-east-py",
+  "elaraai-east-py-std",
+  "elaraai-east-py-io",
+  "elaraai-east-py-datascience",
+  "elaraai-east-py-cli",
+]
+
+# This project is a uv workspace root: each package under packages/python/*
+# is its own member with its own dependency closure (and its own captured
+# execution environment). No [build-system] \u2014 the root is not itself a
+# Python package, just the workspace + the shared runtime dependencies.
+[tool.uv.workspace]
+members = ["packages/python/*"]
+
+[tool.uv.sources]
+${sources}
+`;
+  writeFileSync(join(projectDir, "pyproject.toml"), body);
+}
+function patchNodeWorkspaceRoot(projectDir) {
+  const path = join(projectDir, "package.json");
+  const pkg = JSON.parse(readFileSync(path, "utf8"));
+  const globs = new Set(Array.isArray(pkg.workspaces) ? pkg.workspaces : []);
+  globs.add("packages/node/*");
+  pkg.workspaces = [...globs];
+  pkg.private = true;
+  const scripts = pkg.scripts ?? {};
+  if (typeof scripts.build === "string" && !scripts.build.includes("--workspaces")) {
+    scripts.build = `npm run build --workspaces --if-present && ${scripts.build}`;
+    pkg.scripts = scripts;
+  }
+  writeFileSync(path, `${JSON.stringify(pkg, null, 2)}
+`);
+}
+function excludePackagesFromRootTsconfig(projectDir) {
+  const path = join(projectDir, "tsconfig.json");
+  if (!existsSync(path))
+    return;
+  const tsconfig = JSON.parse(readFileSync(path, "utf8"));
+  const exclude = new Set(tsconfig.exclude ?? []);
+  exclude.add("packages");
+  tsconfig.exclude = [...exclude];
+  writeFileSync(path, `${JSON.stringify(tsconfig, null, 2)}
+`);
+}
+function writeAppWiring(projectDir, names, members) {
+  const imports = members.map((m) => `import { ${m.ident}_task } from "./${m.name}.js";`).join("\n");
+  const list = members.map((m) => `  ${m.ident}_task,`).join("\n");
+  const barrel = `// Generated by create-e3 \u2014 collects one example task per workspace package.
+// Each task's \`environment\` points at its package, so editing one package
+// re-runs only its task. Add packages with \`create-e3 --python-packages=\u2026\`.
+${imports}
+
+export const packageTasks = [
+${list}
+];
+`;
+  mkdirSync(join(projectDir, "src", "packages"), { recursive: true });
+  writeFileSync(join(projectDir, "src", "packages", "index.ts"), barrel);
+  const index = `import e3 from "@elaraai/e3";
+
+import { packageTasks } from "./packages/index.js";
+
+// This app wires one example task per generated workspace package. Every
+// task's \`environment\` is captured independently, so editing one package
+// re-runs only its task \u2014 the other packages stay cached. Add your own
+// inputs, tasks and dataflows here.
+export default e3.package("${names.projectName}", "1.0.0", ...packageTasks);
+`;
+  writeFileSync(join(projectDir, "src", "index.ts"), index);
+}
+function generatePackages(options) {
+  const { projectDir, templateDir, names, version, spec, log } = options;
+  const templateRoot = join(templateDir, "_packages");
+  const members = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const runtime of RUNTIME_ORDER) {
+    const cfg = RUNTIMES[runtime];
+    for (const raw of spec[runtime] ?? []) {
+      const name = raw.trim();
+      if (!name)
+        throw new Error(`--${runtime}-packages contains an empty package name`);
+      if (!cfg.valid.test(name)) {
+        throw new Error(`${cfg.label} package name '${name}' is invalid \u2014 use ${cfg.rule}`);
+      }
+      const prior = seen.get(name);
+      if (prior) {
+        throw new Error(`package name '${name}' is declared twice (${prior} and ${runtime}) \u2014 names must be unique`);
+      }
+      seen.set(name, runtime);
+      members.push({ name, ident: toIdent(name), runtime });
+    }
+  }
+  if (members.length === 0)
+    return;
+  for (const runtime of RUNTIME_ORDER) {
+    if ((spec[runtime]?.length ?? 0) > 0 && !existsSync(join(templateRoot, RUNTIMES[runtime].templateName))) {
+      throw new Error(`${RUNTIMES[runtime].label} packages are not available in this scaffold yet \u2014 remove --${runtime}-packages for now`);
+    }
+  }
+  for (const pkg of members) {
+    stampMember(projectDir, templateRoot, RUNTIMES[pkg.runtime], names, version, pkg);
+  }
+  const py = members.filter((m) => m.runtime === "python").map((m) => m.name);
+  const node = members.filter((m) => m.runtime === "node").map((m) => m.name);
+  if (py.length > 0)
+    writePythonWorkspaceRoot(projectDir, names, py);
+  if (node.length > 0)
+    patchNodeWorkspaceRoot(projectDir);
+  excludePackagesFromRootTsconfig(projectDir);
+  writeAppWiring(projectDir, names, members);
+  const summary = RUNTIME_ORDER.map((r) => ({ r, n: members.filter((m) => m.runtime === r).length })).filter((x) => x.n > 0).map((x) => `${x.n} ${RUNTIMES[x.r].label}`).join(", ");
+  log(`Generated ${members.length} workspace package${members.length === 1 ? "" : "s"} (${summary}).`);
+}
+
 // ../scaffold-core/dist/scaffold.js
 var TEXT_REPLACE_EXT = /* @__PURE__ */ new Set([
   ".ts",
@@ -102,9 +299,9 @@ function transformPackageJson(raw, names, version, manifest, enabled) {
 }
 function walk(dir) {
   const out = [];
-  for (const entry of readdirSync(dir)) {
-    const full = join(dir, entry);
-    if (statSync(full).isDirectory())
+  for (const entry of readdirSync2(dir)) {
+    const full = join2(dir, entry);
+    if (statSync2(full).isDirectory())
       out.push(...walk(full));
     else
       out.push(full);
@@ -117,16 +314,16 @@ function extOf(path) {
   return dot <= 0 ? "" : base.slice(dot);
 }
 function loadManifest(templateDir) {
-  const path = join(templateDir, MANIFEST_FILE);
-  if (!existsSync(path))
+  const path = join2(templateDir, MANIFEST_FILE);
+  if (!existsSync2(path))
     return null;
-  return JSON.parse(readFileSync(path, "utf8"));
+  return JSON.parse(readFileSync2(path, "utf8"));
 }
 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)) {
+  if (!existsSync2(templateDir)) {
     throw new Error(`Template directory not found: ${templateDir}`);
   }
   const manifest = loadManifest(templateDir);
@@ -164,34 +361,39 @@ function scaffold(options) {
   }
   const names = deriveNames(name, cwd);
   const inPlace = name === ".";
-  const projectDir = inPlace ? cwd : join(cwd, names.projectName);
-  if (!inPlace && existsSync(projectDir)) {
+  const projectDir = inPlace ? cwd : join2(cwd, names.projectName);
+  if (!inPlace && existsSync2(projectDir)) {
     throw new Error(`Directory already exists: ${projectDir}`);
   }
-  mkdirSync(projectDir, { recursive: true });
+  mkdirSync2(projectDir, { recursive: true });
   for (const srcPath of walk(templateDir)) {
-    const rel = relative(templateDir, srcPath).replaceAll("\\", "/");
+    const rel = relative2(templateDir, srcPath).replaceAll("\\", "/");
     if (rel === MANIFEST_FILE)
       continue;
+    if (rel.split("/")[0].startsWith("_"))
+      continue;
     if (skip.has(rel))
       continue;
     const destRel = renames[rel] ?? rel;
     const segments = destRel.split("/");
     const last = segments[segments.length - 1];
     segments[segments.length - 1] = DOTFILE_RENAMES[last] ?? last;
-    const destPath = join(projectDir, segments.join("/"));
-    mkdirSync(join(destPath, ".."), { recursive: true });
+    const destPath = join2(projectDir, segments.join("/"));
+    mkdirSync2(join2(destPath, ".."), { recursive: true });
     const baseName = segments[segments.length - 1];
     if (baseName === "package.json") {
-      const transformed = transformPackageJson(readFileSync(srcPath, "utf8"), names, version, manifest, enabled);
-      writeFileSync(destPath, substituteTokens(transformed, names));
+      const transformed = transformPackageJson(readFileSync2(srcPath, "utf8"), names, version, manifest, enabled);
+      writeFileSync2(destPath, substituteTokens(transformed, names));
     } else if (TEXT_REPLACE_EXT.has(extOf(srcPath)) || baseName.startsWith(".")) {
-      writeFileSync(destPath, substituteTokens(readFileSync(srcPath, "utf8"), names));
+      writeFileSync2(destPath, substituteTokens(readFileSync2(srcPath, "utf8"), names));
     } else {
-      writeFileSync(destPath, readFileSync(srcPath));
+      writeFileSync2(destPath, readFileSync2(srcPath));
     }
   }
   log(`Created ${names.projectName} (${kind}) at ${projectDir}`);
+  if (options.packages) {
+    generatePackages({ projectDir, templateDir, names, version, spec: options.packages, log });
+  }
   if (options.install) {
     runInstall(kind, projectDir, enabled, log);
   }
@@ -221,35 +423,36 @@ function runInstall(kind, projectDir, enabled, log) {
 }
 
 // ../scaffold-core/dist/cli.js
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-import { dirname, join as join2 } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { dirname, join as join3 } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 async function runCreateCli(kind, moduleUrl) {
-  const pkgRoot = join2(dirname(fileURLToPath(moduleUrl)), "..");
+  const pkgRoot = join3(dirname(fileURLToPath(moduleUrl)), "..");
   const args = process.argv.slice(2);
   if (args.includes("--help") || args.includes("-h")) {
     printHelp(kind);
     return;
   }
-  const version = JSON.parse(readFileSync2(join2(pkgRoot, "package.json"), "utf8")).version;
-  const templateDir = join2(pkgRoot, "templates", kind);
+  const version = JSON.parse(readFileSync3(join3(pkgRoot, "package.json"), "utf8")).version;
+  const templateDir = join3(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 features = await resolveFeatures(templateDir, args);
-    const result = scaffold({ kind, name, templateDir, version, install, features });
+    const packages = kind === "e3" ? parsePackages(args) : void 0;
+    const features = await resolveFeatures(templateDir, args, packages);
+    const result = scaffold({ kind, name, templateDir, version, install, features, packages });
     printNextSteps(kind, result.projectName, result.inPlace, install, features);
   } catch (err) {
     console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
     process.exit(1);
   }
 }
-async function resolveFeatures(templateDir, args) {
-  const manifestPath = join2(templateDir, "template.json");
-  if (!existsSync2(manifestPath))
+async function resolveFeatures(templateDir, args, packages) {
+  const manifestPath = join3(templateDir, "template.json");
+  if (!existsSync3(manifestPath))
     return {};
-  const manifest = JSON.parse(readFileSync2(manifestPath, "utf8"));
+  const manifest = JSON.parse(readFileSync3(manifestPath, "utf8"));
   const features = {};
   for (const [key, spec] of Object.entries(manifest.features)) {
     if (spec.allOf)
@@ -259,7 +462,9 @@ async function resolveFeatures(templateDir, args) {
   const runnerKeys = Object.keys(manifest.features).filter((k) => k.startsWith("runner:"));
   const runnerName = (key) => key.slice("runner:".length);
   const runnersFlag = args.find((a) => a.startsWith("--runners="));
-  const selectionFlags = ["--tests", "--no-tests", "--ui", "--no-ui", "--platform", "--no-platform", "--eslint", "--no-eslint"].some((f) => args.includes(f)) || Boolean(runnersFlag);
+  const selectionFlags = ["--tests", "--no-tests", "--ui", "--no-ui", "--platform", "--no-platform", "--eslint", "--no-eslint"].some((f) => args.includes(f)) || Boolean(runnersFlag) || // `--python-packages=…` / `--node-packages=…` / `--c-packages=…` are an
+  // explicit non-interactive selection: skip the prompt.
+  Boolean(packages);
   if (args.includes("--tests"))
     features["tests"] = true;
   if (args.includes("--no-tests"))
@@ -285,6 +490,15 @@ async function resolveFeatures(templateDir, args) {
     for (const key of runnerKeys)
       features[key] = chosen.has(runnerName(key));
   }
+  if (packages) {
+    if (packages.python?.length && "runner:east-py" in manifest.features)
+      features["runner:east-py"] = true;
+    if (packages.node?.length && "runner:east-node" in manifest.features)
+      features["runner:east-node"] = true;
+    if (packages.c?.length && "runner:east-c" in manifest.features)
+      features["runner:east-c"] = true;
+    features["platform"] = false;
+  }
   const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !selectionFlags;
   if (!interactive)
     return features;
@@ -317,6 +531,28 @@ async function resolveFeatures(templateDir, args) {
   }
   return features;
 }
+function parsePackages(args) {
+  const grab = (flag) => {
+    const arg = args.find((a) => a === flag || a.startsWith(`${flag}=`));
+    if (arg === void 0)
+      return void 0;
+    const value = arg.startsWith(`${flag}=`) ? arg.slice(flag.length + 1) : "";
+    return value.split(",").map((s) => s.trim()).filter(Boolean);
+  };
+  const python = grab("--python-packages");
+  const node = grab("--node-packages");
+  const c = grab("--c-packages");
+  if (!python && !node && !c)
+    return void 0;
+  const spec = {};
+  if (python)
+    spec.python = python;
+  if (node)
+    spec.node = node;
+  if (c)
+    spec.c = c;
+  return spec;
+}
 async function askYesNo(rl, question, def) {
   const answer = (await rl.question(`${question} [${def ? "Y/n" : "y/N"}] `)).trim().toLowerCase();
   if (answer === "")
@@ -336,6 +572,12 @@ function printHelp(kind) {
     console.log("  --ui | --no-ui               include east-ui + e3-ui UI components (default: no)");
     console.log("  --platform | --no-platform   include a project-owned platform module (TS-East; +Python when east-py is on) (default: no)");
     console.log("  --runners=east-node,east-c,east-py   East runtimes to include (default: all)");
+    console.log("");
+    console.log("  Split platform code into separate workspace packages, each with its own");
+    console.log("  execution environment (editing one re-runs only its tasks):");
+    console.log("  --python-packages=pricing,common   uv workspace members (packages/python/*)");
+    console.log("  --node-packages=api                npm workspace members (packages/node/*)");
+    console.log("  --c-packages=solver                native binaries wired via a tools env (packages/native/*)");
   }
   console.log("");
   console.log("Run interactively (a TTY with no feature flags) to be prompted for these.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elaraai/create-e3",
-  "version": "1.0.30",
+  "version": "1.0.31",
   "description": "Scaffold a new e3 project (BSL-1.1, Node + Python, durable execution): npm create @elaraai/e3",
   "type": "module",
   "bin": {

package/templates/e3/_packages/c/Makefile

@@ -0,0 +1,16 @@
+# Builds the __PACKAGE_NAME__ tool -> build/__PACKAGE_NAME__.
+#
+# e3 captures this binary into the exported bundle via the task's
+# `environment: { tools: { files: [...] } }`, so rebuilding it changes the
+# environment hash and re-runs only the tasks that use it. Build before export:
+#   make -C packages/native/__PACKAGE_NAME__
+CC ?= cc
+CFLAGS ?= -O2 -Wall -Wextra
+
+build/__PACKAGE_NAME__: src/__PACKAGE_NAME__.c
+	mkdir -p build
+	$(CC) $(CFLAGS) -o $@ $<
+
+.PHONY: clean
+clean:
+	rm -rf build

package/templates/e3/_packages/c/_app.ts

@@ -0,0 +1,22 @@
+import e3 from "@elaraai/e3";
+import { East, ArrayType, FloatType } from "@elaraai/east";
+
+// A C tool captured via `environment: { tools }`. Unlike python/node packages,
+// e3 does NOT auto-derive a tools environment — you attach the prebuilt binary
+// explicitly, and rebuilding it changes the env hash so only this task re-runs.
+// Build it first: `make -C packages/native/__PACKAGE_NAME__`.
+//
+// This example passes a value through the tool unchanged (the scaffold binary is
+// a passthrough). Replace src/__PACKAGE_NAME__.c with real native logic — embed
+// east-c to decode / compute / encode the BEAST2 dataset files.
+const __PACKAGE_IDENT___values = e3.input("__PACKAGE_IDENT___values", ArrayType(FloatType), [1.0, 2.0, 3.0]);
+
+export const __PACKAGE_IDENT___task = e3.customTask(
+  "__PACKAGE_IDENT___tool",
+  [__PACKAGE_IDENT___values],
+  ArrayType(FloatType),
+  (_$, inputs, output) => East.str`__PACKAGE_NAME__ ${inputs.get(0n)} ${output}`,
+  {
+    environment: { tools: { files: ["packages/native/__PACKAGE_NAME__/build/__PACKAGE_NAME__"] } },
+  },
+);

package/templates/e3/_packages/c/src/__PACKAGE_NAME__.c

@@ -0,0 +1,36 @@
+/*
+ * The __PACKAGE_NAME__ tool for __DISPLAY_NAME__ — a prebuilt native binary
+ * captured into the e3 bundle via `environment: { tools: { files: [...] } }`.
+ *
+ * A custom-runner tool is invoked as `__PACKAGE_NAME__ <input> <output>`: it
+ * reads the input dataset file and writes the output dataset file, both
+ * BEAST2-encoded East values. This example is a PASSTHROUGH (it copies input to
+ * output — valid when the task's input and output types match) so the scaffold
+ * stays dependency-free and builds with a plain C compiler.
+ *
+ * For real native computation, embed the east-c runtime to decode the input,
+ * compute, and encode the output BEAST2 value (see the docs on custom C
+ * runners). A rebuild changes the captured binary's hash, so e3 re-runs only
+ * the tasks wired to this tool.
+ */
+#include <stdio.h>
+
+int main(int argc, char **argv) {
+    if (argc < 3) {
+        fprintf(stderr, "usage: %s <input> <output>\n", argv[0]);
+        return 2;
+    }
+    FILE *in = fopen(argv[1], "rb");
+    if (!in) { perror("open input"); return 1; }
+    FILE *out = fopen(argv[2], "wb");
+    if (!out) { perror("open output"); fclose(in); return 1; }
+
+    unsigned char buf[65536];
+    size_t n;
+    while ((n = fread(buf, 1, sizeof buf, in)) > 0) {
+        if (fwrite(buf, 1, n, out) != n) { perror("write output"); fclose(in); fclose(out); return 1; }
+    }
+    fclose(in);
+    fclose(out);
+    return 0;
+}

package/templates/e3/_packages/node/_app.ts

@@ -0,0 +1,25 @@
+import e3 from "@elaraai/e3";
+import { East, IntegerType, FloatType } from "@elaraai/east";
+
+// TS-East mirror of @__PROJECT_NAME__/__PACKAGE_NAME__'s platform function —
+// same dotted "__PACKAGE_NAME__.example" name + signature. Keep this in lockstep
+// with packages/node/__PACKAGE_NAME__/src/platform.ts.
+const example = East.platform("__PACKAGE_NAME__.example", [IntegerType, FloatType], IntegerType);
+
+const value = e3.input("__PACKAGE_IDENT___value", IntegerType, 21n);
+const factor = e3.input("__PACKAGE_IDENT___factor", FloatType, 2.0);
+
+// No `environment` — e3 derives it from the `{ custom: "@__PROJECT_NAME__/__PACKAGE_NAME__" }`
+// platform reference below, capturing packages/node/__PACKAGE_NAME__'s npm
+// workspace closure into the bundle. Editing that package re-runs only this
+// task; sibling packages stay cached.
+export const __PACKAGE_IDENT___task = e3.task(
+  "__PACKAGE_IDENT___example",
+  [value, factor],
+  East.function([IntegerType, FloatType], IntegerType, ($, v, f) => {
+    $.return(example(v, f));
+  }),
+  {
+    runner: { runtime: "east-node", platforms: [{ custom: "@__PROJECT_NAME__/__PACKAGE_NAME__" }] },
+  },
+);

package/templates/e3/_packages/node/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@__PROJECT_NAME__/__PACKAGE_NAME__",
+  "version": "1.0.0",
+  "description": "The __PACKAGE_NAME__ platform package for __DISPLAY_NAME__",
+  "type": "module",
+  "private": true,
+  "exports": {
+    "./platform": "./dist/platform.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@elaraai/east": "^__VERSION__",
+    "@elaraai/east-node-std": "^__VERSION__"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}

package/templates/e3/_packages/node/src/platform.ts

@@ -0,0 +1,17 @@
+import { East, IntegerType, FloatType } from "@elaraai/east";
+
+// The east-node platform function owned by @__PROJECT_NAME__/__PACKAGE_NAME__.
+// Platform functions let East call native TS/Node code East can't express. Its
+// dotted "__PACKAGE_NAME__.example" name + signature mirror the TS-East
+// declaration the app calls (src/packages/__PACKAGE_NAME__.ts) — keep the two
+// in lockstep. Add native dependencies to this package's package.json and use
+// them in the implementation below.
+const example = East.platform("__PACKAGE_NAME__.example", [IntegerType, FloatType], IntegerType);
+
+const exampleImpl = example.implement(
+  (value: bigint, factor: number): bigint => BigInt(Math.ceil(Number(value) * factor)),
+);
+
+// The PlatformFunction[] the east-node runner loads via the package's
+// `@__PROJECT_NAME__/__PACKAGE_NAME__/platform` export.
+export default [exampleImpl];

package/templates/e3/_packages/node/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "exclude": [
+    "dist"
+  ],
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "module": "nodenext",
+    "target": "esnext",
+    "lib": [
+      "esnext"
+    ],
+    "declaration": false,
+    "sourceMap": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true
+  }
+}

package/templates/e3/_packages/python/_app.ts

@@ -0,0 +1,26 @@
+import e3 from "@elaraai/e3";
+import { East, ArrayType, FloatType } from "@elaraai/east";
+
+// TS-East mirror of `packages/python/__PACKAGE_NAME__`'s @platform_function —
+// same dotted "__PACKAGE_NAME__.example" name, same signature. Keep this in
+// lockstep with packages/python/__PACKAGE_NAME__/src/__PACKAGE_NAME__/example.py.
+const example = East.platform("__PACKAGE_NAME__.example", [ArrayType(FloatType)], FloatType);
+
+const values = e3.input("__PACKAGE_IDENT___values", ArrayType(FloatType), [1.0, 2.0, 3.0]);
+
+// No `environment` needed: e3 derives it from the `{ custom: "__PACKAGE_NAME__" }`
+// platform reference below — at export it captures packages/python/__PACKAGE_NAME__'s
+// dependency closure into the bundle. Editing anything under that package re-runs
+// only this task; sibling packages stay cached. (To override — e.g. pin a
+// container image, or add prebuilt `tools` binaries — add an explicit
+// `environment:` here.)
+export const __PACKAGE_IDENT___task = e3.task(
+  "__PACKAGE_IDENT___example",
+  [values],
+  East.function([ArrayType(FloatType)], FloatType, ($, v) => {
+    $.return(example(v));
+  }),
+  {
+    runner: { runtime: "east-py", platforms: [{ custom: "__PACKAGE_NAME__" }, "east-py-std"] },
+  },
+);

package/templates/e3/_packages/python/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "__PACKAGE_NAME__"
+version = "0.1.0"
+description = "The __PACKAGE_NAME__ platform package for __DISPLAY_NAME__"
+requires-python = ">=3.11"
+dependencies = [
+  "elaraai-east-py",
+]
+
+# Hatchling gives byte-reproducible sdists, so this package's captured
+# environment hash is stable across exports. (Legacy setuptools embeds file
+# mtimes into the sdist, which would re-invalidate the environment — and re-run
+# every task wired to it — on every export.) Keep hatchling here.
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

package/templates/e3/_packages/python/src/__PACKAGE_NAME__/__init__.py

@@ -0,0 +1,18 @@
+"""The ``__PACKAGE_NAME__`` platform package — its own execution environment.
+
+Everything under ``packages/python/__PACKAGE_NAME__`` is captured as ONE
+environment when a task wired to it is exported. Editing this package changes
+only its environment hash, so only the tasks that declare
+``environment: { python: { project: "packages/python/__PACKAGE_NAME__" } }``
+re-run — sibling packages are left untouched. That package boundary IS the
+change-detection granularity.
+
+``east-py run -p __PACKAGE_NAME__`` imports this package and reads the top-level
+``platform`` list below. To add a function: create a module beside this file
+(e.g. ``pricing.py``) ending with ``pricing_impl = platform_functions(__name__)``,
+then import and spread it into ``platform``.
+"""
+
+from .example import example_impl
+
+platform = [*example_impl]

package/templates/e3/_packages/python/src/__PACKAGE_NAME__/example.py

@@ -0,0 +1,27 @@
+"""An example Python platform function owned by the ``__PACKAGE_NAME__`` package.
+
+Platform functions let East call NATIVE Python (numpy, pandas, scikit-learn, …)
+that East itself can't express. The ``@platform_function`` is bound to East by
+its dotted ``"__PACKAGE_NAME__.<fn>"`` name, which the TypeScript declaration in
+``src/packages/__PACKAGE_NAME__.ts`` mirrors exactly — keep the two in lockstep.
+Add native dependencies to this package's ``pyproject.toml`` and import them
+inside the body.
+"""
+
+from east.runtime.platform import platform_function, platform_functions
+from east.types.types import ArrayType, FloatType
+
+
+@platform_function(
+    inputs=[ArrayType(FloatType)],
+    output=FloatType,
+    name="__PACKAGE_NAME__.example",
+)
+def example(values):
+    """Example: the mean of a list of floats. Replace with your own logic."""
+    values = list(values)
+    return sum(values) / len(values) if values else 0.0
+
+
+# The platform functions defined in THIS module, in definition order.
+example_impl = platform_functions(__name__)