@kexhq/kex 0.4.0-alpha.2

package/README.md

@@ -0,0 +1,94 @@
+# @kexhq/kex
+
+The [Kex](https://github.com/kexhq/kex) language interpreter compiled to
+WebAssembly, packaged for embedding a Kex REPL in a web page or a Node
+script. This is the same wasm binary built and tested in the main repo
+(`src/wasm_repl.cxx`, `web/index.html`).
+
+Published to the public npm registry as [`@kexhq/kex`](https://www.npmjs.com/package/@kexhq/kex),
+and mirrored to GitHub Packages for internal consumers already wired to that
+path (e.g. kex.run's site repo).
+
+## Status
+
+**Pre-release.** The package's version follows the language's `VERSION` file:
+
+- Every push to the repo publishes `<VERSION>-dev.<sha>` under the `next`
+  dist-tag (e.g. `0.3.0-beta.dev.a1b2c3d`) — a dev build names the version it
+  is working toward, distinguished by revision, exactly like a native
+  `kex --version` built from the same tree.
+- A release publishes the plain `VERSION` (`0.3.0-beta`) with the same
+  dist-tag rule as the container images: `latest` for a stable release, the
+  channel name (`rc`, `beta`) for a pre-release. The `version` field in
+  `package.json` is a placeholder — the number is stamped at publish time.
+
+Expect breaking changes without notice until 1.0.0; pin a version if you need
+reproducible builds.
+
+**Known limitation:** none currently — the Asyncify/JS-interop bug that
+used to cause duplicated output and lost state for `receive`,
+`receive timeout:`, and `Task.await` is fixed.
+
+## Installing
+
+```
+npm install @kexhq/kex@next
+```
+
+## Usage
+
+```js
+import { Kex } from "@kexhq/kex";
+
+const session = await Kex.create();
+
+// Evaluate one chunk of Kex source at a time — state (let/var bindings,
+// spawned processes) persists across calls on the same session, exactly
+// like a real REPL.
+console.log(await session.eval("1 + 2"));
+// => "=> 3 : Int\n"
+
+await session.eval("let x = 5");
+console.log(await session.eval("x + 10"));
+// => "=> 15 : Int\n"
+
+// Tab completion — see web/index.html in the main repo for a full
+// reference client (word-break-character scanning, history, line editing).
+console.log(session.complete("IO.printL", 0, "IO.printL"));
+// => ["IO.printLine"]
+
+session.destroy();
+```
+
+Ships with TypeScript definitions (`Kex`, `KexModuleOptions`) — no `@types`
+package needed, and no `new Kex(...)`: the constructor is private, use
+`Kex.create()`.
+
+Multi-line input (`do ... end` blocks) needs to be accumulated into one
+string before calling `eval` — this package doesn't do that for you (see
+`web/index.html`'s `countBlocks()` for the exact logic the real REPL uses to
+decide when a block is complete).
+
+Output already contains ANSI color escape codes (matching the native CLI's
+REPL exactly) — render it through a real terminal emulator (e.g.
+[xterm.js](https://xtermjs.org/), as `web/index.html` does) rather than
+stripping them, unless you specifically want plain text.
+
+## For kex.run specifically
+
+This is the package kex.run is expected to import as its in-browser
+interpreter. Float on `next` for development; for a deployed build pin an
+exact version — a released one (`@kexhq/kex@0.3.0-beta`) or a specific dev
+build (`@kexhq/kex@0.3.0-beta.dev.a1b2c3d`) — since `next` moves on every
+push.
+
+## Building locally
+
+From the main repo, with `emsdk` active (pinned to 5.0.7 — see
+`third_party/gmp-wasm/README.md`):
+
+```
+cd packages/kex
+npm run prepack   # builds build-wasm/ if needed, assembles dist/
+npm pack          # produces a .tgz you can npm install locally to test
+```

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+// Type definitions for @kexhq/kex
+
+/** Extra options forwarded to the underlying Emscripten module factory. */
+export interface KexModuleOptions {
+  locateFile?: (path: string, prefix: string) => string;
+  [key: string]: unknown;
+}
+
+/**
+ * A Kex REPL session backed by the wasm interpreter. Internal state (the
+ * Emscripten module and the C-side session handle) is fully private —
+ * construct instances via Kex.create(), not `new Kex(...)`.
+ */
+export class Kex {
+  private constructor(module: unknown, session: number);
+
+  /** Creates a new, independent Kex REPL session backed by the wasm interpreter. */
+  static create(moduleOptions?: KexModuleOptions): Promise<Kex>;
+
+  /**
+   * Evaluates one chunk of Kex source against this session's persistent
+   * interpreter state. State (`let`/`var` bindings, spawned processes)
+   * persists across calls on the same session, like a real REPL.
+   *
+   * Multi-line `do ... end` blocks must be accumulated into one string by
+   * the caller before calling eval — see web/index.html in the main repo
+   * for the exact `countBlocks()` logic the real REPL uses.
+   *
+   * The returned string already contains ANSI color escape codes (matching
+   * the native CLI's REPL exactly) — render it through a real terminal
+   * emulator (e.g. xterm.js) rather than stripping them, unless you
+   * specifically want plain text.
+   */
+  eval(source: string): Promise<string>;
+
+  /**
+   * Tab completion, reusing the same logic the native REPL's readline
+   * integration uses. `line` is the current input line, `start` is the
+   * index where the word under the cursor begins, `text` is that word
+   * itself. Returns the list of completions (already rewritten to what
+   * should be inserted in place of `text`).
+   */
+  complete(line: string, start: number, text: string): string[];
+
+  /** Frees this session's underlying interpreter state. Safe to call more than once. */
+  destroy(): void;
+
+  /** The REPL banner with version info, matching the native CLI exactly. */
+  banner(): string;
+
+  /** Kex version string (e.g. "0.2.0"). */
+  version(): string;
+}

package/dist/index.mjs

@@ -0,0 +1,109 @@
+// Thin wrapper around the wasm REPL bindings (src/wasm_repl.cxx in the main
+// repo) for consumption as an npm package — this is what kex.run imports to
+// embed the interpreter. At publish time, the "prepack" build step (see
+// ../README.md) copies this file into dist/ alongside the built
+// kex_repl_wasm.js/.wasm/.data, so everything resolves relative to this same
+// directory at runtime (works in both Node and a bundler, since it's plain
+// import.meta.url-relative resolution, no cwd-dependent paths).
+import createKexReplModule from "./kex_repl_wasm.js";
+
+// Private fields keep the raw Emscripten Module and the C-side session
+// pointer out of the public API entirely — callers only ever see eval/
+// complete/destroy, never the ccall plumbing underneath.
+export class Kex {
+  #module;
+  #session;
+  #destroyed = false;
+
+  // Not called directly — use Kex.create(), since standing up the wasm
+  // module is inherently async and a constructor can't await.
+  constructor(module, session) {
+    this.#module = module;
+    this.#session = session;
+  }
+
+  /** Creates a new, independent Kex REPL session backed by the wasm interpreter. */
+  static async create(moduleOptions = {}) {
+    const module = await createKexReplModule({
+      // In Node, the preload-file package (kex_repl_wasm.data) is fetched
+      // via a plain fs.readFileSync(path) call, which doesn't accept a
+      // file:// URL string — only a real filesystem path. url.pathname
+      // (not .href) gives that directly on POSIX. In a browser this needs
+      // an actual URL for fetch(), hence .href there instead.
+      locateFile: (path) => {
+        const url = new URL(path, import.meta.url);
+        return typeof window === "undefined" ? url.pathname : url.href;
+      },
+      ...moduleOptions,
+    });
+    const session = module.ccall("kex_repl_create", "number", [], []);
+    return new Kex(module, session);
+  }
+
+  #assertAlive() {
+    if (this.#destroyed) throw new Error("this Kex session has already been destroyed");
+  }
+
+  /**
+   * Evaluates one chunk of Kex source against this session's persistent
+   * interpreter state. State (`let`/`var` bindings, spawned processes)
+   * persists across calls on the same session, like a real REPL.
+   *
+   * Multi-line `do ... end` blocks must be accumulated into one string by
+   * the caller before calling eval — see web/index.html in the main repo
+   * for the exact `countBlocks()` logic the real REPL uses.
+   *
+   * The returned string already contains ANSI color escape codes (matching
+   * the native CLI's REPL exactly) — render it through a real terminal
+   * emulator (e.g. xterm.js) rather than stripping them, unless you
+   * specifically want plain text.
+   */
+  async eval(source) {
+    this.#assertAlive();
+    // kex_repl_eval is void-returning on purpose — see src/wasm_repl.cxx's
+    // own doc comment: a direct return value from an Asyncify-instrumented
+    // export wasn't reliably reaching the JS caller through ccall's async
+    // plumbing, so the result is fetched via a second, ordinary synchronous
+    // call instead (kex_repl_last_result never touches Asyncify).
+    await this.#module.ccall(
+      "kex_repl_eval", null,
+      ["number", "string"], [this.#session, source],
+      { async: true }
+    );
+    return this.#module.ccall("kex_repl_last_result", "string", ["number"], [this.#session]);
+  }
+
+  /**
+   * Tab completion, reusing the same logic the native REPL's readline
+   * integration uses. `line` is the current input line, `start` is the
+   * index where the word under the cursor begins, `text` is that word
+   * itself. Returns the list of completions (already rewritten to what
+   * should be inserted in place of `text`).
+   */
+  complete(line, start, text) {
+    this.#assertAlive();
+    const raw = this.#module.ccall(
+      "kex_repl_complete", "string",
+      ["number", "string", "number", "string"],
+      [this.#session, line, start, text]
+    );
+    return raw.split("\n").filter((m) => m.length > 0);
+  }
+
+  /** Frees this session's underlying interpreter state. Safe to call more than once. */
+  destroy() {
+    if (this.#destroyed) return;
+    this.#module.ccall("kex_repl_destroy", null, ["number"], [this.#session]);
+    this.#destroyed = true;
+  }
+
+  /** The REPL banner with version info, matching the native CLI exactly. */
+  banner() {
+    return this.#module.ccall("kex_repl_banner", "string", [], []);
+  }
+
+  /** Kex version string (e.g. "0.2.0"). */
+  version() {
+    return this.#module.ccall("kex_version", "string", [], []);
+  }
+}