feat(types): add @opentf/esrun-types TypeScript definitions

Hand-written .d.ts for the runtime: standard modules (runtime:process,
runtime:path, runtime:fs) in types/, publishable as @opentf/esrun-types.
Ambient `declare module` blocks so editors type `import … from "runtime:fs"`;
add via tsconfig `types` or a triple-slash reference. Signatures match the
implemented surface; validated with `tsc --strict`. CHANGELOG.

Author: Thanga-Ganapathy

CHANGELOG.md

@@ -8,6 +8,12 @@ pre-`0.1.0` and the public API is unstable.
 
 ### Added
 
+- **`@opentf/esrun-types`** — hand-written TypeScript definitions for the
+  `runtime:` standard modules (`runtime:process`, `runtime:path`, `runtime:fs`),
+  in [`types/`](types/), for editor completion and type-checking. Ambient
+  `declare module` blocks; add via `tsconfig` `types` or a triple-slash
+  reference. Validated with `tsc --strict`.
+
 - **`runtime:fs`** — modern, Blob-based file I/O, the third `runtime:` standard
   module (SPEC §11, DECISIONS D25). `file(path)` is a lazy, Blob-like handle
   (`text`/`json`/`bytes`/`arrayBuffer`/`stream`/`exists`/`stat`/`write`/`delete`,

types/README.md

@@ -0,0 +1,43 @@
+# @opentf/esrun-types
+
+TypeScript type definitions for [ES Runtime](https://es-runtime.opentechf.org)
+(`esrun`) — the `runtime:` standard modules, so your editor gives completion and
+type-checking for `import … from "runtime:process" | "runtime:path" | "runtime:fs"`.
+
+## Install
+
+```sh
+bun add -d @opentf/esrun-types   # or: npm i -D @opentf/esrun-types
+```
+
+## Use
+
+Add the package to your `tsconfig.json`:
+
+```json
+{ "compilerOptions": { "types": ["@opentf/esrun-types"] } }
+```
+
+…or reference it from one file:
+
+```ts
+/// <reference types="@opentf/esrun-types" />
+```
+
+Then the `runtime:` imports are fully typed:
+
+```ts
+import { file, write } from "runtime:fs";
+
+const cfg = await file("./config/app.json").json();
+await write("./out/result.txt", "done", { append: true });
+```
+
+esrun targets the WinterTC web-platform surface, so web globals (`URL`, `Blob`,
+`ReadableStream`, `Response`, …) come from your `lib` (`dom` or `webworker`).
+
+## Covered
+
+- `runtime:process` — `env`, `args`, `platform`, `arch`, `cwd()`, `exit()`
+- `runtime:path` — `join`, `resolve`, `normalize`, `dirname`, `basename`, `extname`, `parse`, `relative`, `isAbsolute`, `sep`, `delimiter`, `fromFileURL`, `toFileURL`
+- `runtime:fs` — `file()`, `write()`, `readDir`, `stat`, `exists`, `mkdir`, `remove`, `rename`, `Glob`

types/index.d.ts

@@ -0,0 +1,12 @@
+// Type definitions for ES Runtime (esrun) — the `runtime:` standard modules.
+// Ambient `declare module` blocks: include this package and editors resolve
+// `import … from "runtime:fs"` (and process/path) with full completion + types.
+//
+// Setup (tsconfig.json):
+//   { "compilerOptions": { "types": ["@opentf/esrun-types"] } }
+// or a triple-slash reference in one file:
+//   /// <reference types="@opentf/esrun-types" />
+
+/// <reference path="./runtime-process.d.ts" />
+/// <reference path="./runtime-path.d.ts" />
+/// <reference path="./runtime-fs.d.ts" />

types/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@opentf/esrun-types",
+  "version": "0.1.0",
+  "description": "TypeScript type definitions for ES Runtime (esrun) — the runtime: standard modules (process, path, fs).",
+  "types": "index.d.ts",
+  "files": [
+    "index.d.ts",
+    "runtime-process.d.ts",
+    "runtime-path.d.ts",
+    "runtime-fs.d.ts"
+  ],
+  "keywords": ["esrun", "es-runtime", "opentf", "types", "runtime"],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Open-Tech-Foundation/ES-Runtime.git",
+    "directory": "types"
+  },
+  "homepage": "https://es-runtime.opentechf.org/api",
+  "publishConfig": {
+    "access": "public"
+  }
+}

types/runtime-fs.d.ts

@@ -0,0 +1,131 @@
+declare module "runtime:fs" {
+  /** A path: a string, a `file:` URL, or a {@link FsFile} handle. */
+  export type PathLike = string | URL | FsFile;
+
+  /** Anything `write` accepts as the body to write. */
+  export type WriteInput =
+    | string
+    | Blob
+    | ArrayBuffer
+    | ArrayBufferView
+    | Response
+    | ReadableStream<Uint8Array>
+    | FsFile;
+
+  /** File metadata, from {@link stat} / {@link FsFile.stat} (follows symlinks). */
+  export interface Stat {
+    /** Size in bytes. */
+    size: number;
+    isFile: boolean;
+    isDir: boolean;
+    isSymlink: boolean;
+    /** Modification time in ms since the Unix epoch, or `null` if unavailable. */
+    mtimeMs: number | null;
+  }
+
+  /** One entry of a directory listing, from {@link readDir}. */
+  export interface DirEntry {
+    name: string;
+    isFile: boolean;
+    isDir: boolean;
+    isSymlink: boolean;
+  }
+
+  /** Options for {@link Glob.scan}. */
+  export interface GlobScanOptions {
+    /** Directory to scan (default `"."`). */
+    cwd?: string;
+    /** Match dotfiles / dot-directories (default `false`). */
+    dot?: boolean;
+    /** Yield absolute paths instead of paths relative to `cwd` (default `false`). */
+    absolute?: boolean;
+    /** Yield only files, skipping directories (default `true`). */
+    onlyFiles?: boolean;
+  }
+
+  /**
+   * A lazy, Blob-like file handle from {@link file}. Nothing is read until a
+   * read method is called. **All methods are async.**
+   */
+  export interface FsFile {
+    /** The path this handle points at. */
+    readonly path: string;
+    /** Read the whole file as text (UTF-8). */
+    text(): Promise<string>;
+    /** Read and `JSON.parse` the file. */
+    json(): Promise<any>;
+    /** Read the whole file as bytes. */
+    bytes(): Promise<Uint8Array>;
+    /** Read the whole file as an `ArrayBuffer`. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** A `ReadableStream` of the file's bytes. */
+    stream(): ReadableStream<Uint8Array>;
+    /** Whether the file exists. */
+    exists(): Promise<boolean>;
+    /** File metadata (follows symlinks). */
+    stat(): Promise<Stat>;
+    /** Write `data` to this file; resolves to bytes written. */
+    write(data: WriteInput, options?: { append?: boolean }): Promise<number>;
+    /** Delete this file. */
+    delete(): Promise<void>;
+    /**
+     * A `WritableStream` sink for incremental / piped writes:
+     * `await readable.pipeTo(file("out").writable())`. The first chunk
+     * truncates the file; later chunks append.
+     */
+    writable(): WritableStream<Uint8Array>;
+  }
+
+  /**
+   * Glob matching and scanning. Patterns support `*`, `**`, `?`, `[classes]`,
+   * and `{a,b}` alternation; `*` does not cross `/`, `**` does.
+   */
+  export class Glob {
+    constructor(pattern: string);
+    /** Pure pattern match against a path (synchronous; no I/O). */
+    match(path: PathLike): boolean;
+    /** Walk the (jailed) filesystem, yielding matching paths. Needs `FileRead`. */
+    scan(options?: string | GlobScanOptions): AsyncIterableIterator<string>;
+  }
+
+  /** A lazy, Blob-like handle for `path`. */
+  export function file(path: PathLike): FsFile;
+
+  /** Write any web body to `dest`; resolves to bytes written. Needs `FileWrite`. */
+  export function write(
+    dest: PathLike,
+    input: WriteInput,
+    options?: { append?: boolean },
+  ): Promise<number>;
+
+  /** List the entries of a directory. Needs `FileRead`. */
+  export function readDir(path: PathLike): Promise<DirEntry[]>;
+
+  /** Metadata for `path` (follows symlinks). Needs `FileRead`. */
+  export function stat(path: PathLike): Promise<Stat>;
+
+  /** Whether `path` exists (missing → `false`). Needs `FileRead`. */
+  export function exists(path: PathLike): Promise<boolean>;
+
+  /** Create a directory (`recursive` creates parents). Needs `FileWrite`. */
+  export function mkdir(path: PathLike, options?: { recursive?: boolean }): Promise<void>;
+
+  /** Remove a file or (with `recursive`) a directory tree. Needs `FileWrite`. */
+  export function remove(path: PathLike, options?: { recursive?: boolean }): Promise<void>;
+
+  /** Rename/move an entry (both jailed). Needs `FileWrite`. */
+  export function rename(from: PathLike, to: PathLike): Promise<void>;
+
+  const fs: {
+    file: typeof file;
+    write: typeof write;
+    readDir: typeof readDir;
+    stat: typeof stat;
+    exists: typeof exists;
+    mkdir: typeof mkdir;
+    remove: typeof remove;
+    rename: typeof rename;
+    Glob: typeof Glob;
+  };
+  export default fs;
+}

types/runtime-path.d.ts

@@ -0,0 +1,71 @@
+declare module "runtime:path" {
+  /** The parsed shape of a path, from {@link parse}. */
+  export interface ParsedPath {
+    /** The root of the path (`"/"`, `"C:\\"`, or `""`). */
+    root: string;
+    /** The directory portion. */
+    dir: string;
+    /** The final segment, including any extension. */
+    base: string;
+    /** The final segment without its extension. */
+    name: string;
+    /** The extension, including the leading dot (or `""`). */
+    ext: string;
+  }
+
+  /** Path segment separator for the host OS (`"/"` or `"\\"`). */
+  export const sep: string;
+
+  /** Path list delimiter for the host OS (`":"` or `";"`). */
+  export const delimiter: string;
+
+  /** Whether `p` is an absolute path. */
+  export function isAbsolute(p: string): boolean;
+
+  /** Collapses `.`/`..` and redundant separators. */
+  export function normalize(p: string): string;
+
+  /** Joins segments with the separator, then normalizes. */
+  export function join(...segments: string[]): string;
+
+  /** Resolves to an absolute path, anchoring at `cwd()` if no segment is absolute. */
+  export function resolve(...segments: string[]): string;
+
+  /** The directory portion of `p`. */
+  export function dirname(p: string): string;
+
+  /** The final segment of `p`. */
+  export function basename(p: string): string;
+
+  /** The extension of the final segment, including the dot (or `""`). */
+  export function extname(p: string): string;
+
+  /** Splits `p` into `{ root, dir, base, name, ext }`. */
+  export function parse(p: string): ParsedPath;
+
+  /** Relative path from `from` to `to` (both resolved first). */
+  export function relative(from: string, to: string): string;
+
+  /** Converts a `file:` URL to a path. */
+  export function fromFileURL(url: string | URL): string;
+
+  /** Converts a path (resolved to absolute) to a `file:` URL. */
+  export function toFileURL(p: string): URL;
+
+  const path: {
+    sep: typeof sep;
+    delimiter: typeof delimiter;
+    isAbsolute: typeof isAbsolute;
+    normalize: typeof normalize;
+    join: typeof join;
+    resolve: typeof resolve;
+    dirname: typeof dirname;
+    basename: typeof basename;
+    extname: typeof extname;
+    parse: typeof parse;
+    relative: typeof relative;
+    fromFileURL: typeof fromFileURL;
+    toFileURL: typeof toFileURL;
+  };
+  export default path;
+}

types/runtime-process.d.ts

@@ -0,0 +1,39 @@
+declare module "runtime:process" {
+  /**
+   * Environment variables as a mutable in-process object, seeded from a host
+   * snapshot taken when the module is evaluated. Reads, writes, and deletes work
+   * in-process; they do not propagate to the host process or to child processes.
+   */
+  export const env: Record<string, string>;
+
+  /**
+   * Program arguments after the runtime binary and the script (or `-e` snippet).
+   * Frozen; excludes the executable and script path.
+   */
+  export const args: readonly string[];
+
+  /** Host operating system — the OS-native value (`"linux"`, `"macos"`, `"windows"`, …). */
+  export const platform: string;
+
+  /** Host CPU architecture — the OS-native value (`"x86_64"`, `"aarch64"`, `"arm"`, …). */
+  export const arch: string;
+
+  /** The current working directory (a function — it can change during a run). */
+  export function cwd(): string;
+
+  /**
+   * Records the exit code and halts execution immediately — code after the call
+   * does not run.
+   */
+  export function exit(code?: number): never;
+
+  const process: {
+    env: typeof env;
+    args: typeof args;
+    platform: typeof platform;
+    arch: typeof arch;
+    cwd: typeof cwd;
+    exit: typeof exit;
+  };
+  export default process;
+}