@telorun/shell 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+# SUSTAINABLE USE LICENSE (Fair-code)
+
+Copyright (c) 2026 CodeNet Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
+
+1. ANTI-COMPETITION RESTRICTION: The Software may not be provided to third parties as a managed service, commercial SaaS (Software-as-a-Service), PaaS (Platform-as-a-Service), BaaS (Backend-as-a-Service), or similar offering where the primary value provided to the user is the functionality of the Software itself, without a separate commercial license from the copyright holder.
+
+2. PERMITTED COMMERCIAL USE: You are free to use the Software to build, host, and monetize your own commercial applications, products, and services, provided such use does not violate Clause 1.
+
+3. ATTRIBUTION: This copyright notice and license must be included in all copies or substantial portions of the Software.
+
+4. CONTRIBUTIONS: Contributions to the Software are welcome and encouraged. By contributing, you agree that your contributions may be incorporated into the Software and distributed under this license.
+
+5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
+
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact <contact@codenet.pl>.

package/README.md

@@ -0,0 +1,92 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/telorun/telo/main/assets/telo.png" alt="Telo" width="200" />
+</p>
+
+<h1 align="center">Telo</h1>
+
+<p align="center">Runtime for declarative backends.</p>
+
+<p align="center">
+  <a href="https://github.com/telorun/telo/actions/workflows/test.yml"><img alt="Tests" src="https://github.com/telorun/telo/actions/workflows/test.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@telorun/cli"><img alt="node" src="https://img.shields.io/node/v/@telorun/cli" /></a>
+  <br />
+  <a href="https://github.com/telorun/telo/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/telorun/telo" /></a>
+  <a href="https://github.com/telorun/telo/issues"><img alt="Issues" src="https://img.shields.io/github/issues/telorun/telo" /></a>
+  <a href="https://github.com/telorun/telo/pulls"><img alt="Pull requests" src="https://img.shields.io/github/issues-pr/telorun/telo" /></a>
+  <br />
+  <img alt="Changesets" src="https://img.shields.io/badge/maintained%20with-changesets-176de3" />
+</p>
+
+Telo is an execution engine (Micro-Kernel) that runs logic defined entirely in YAML manifests. Instead of writing imperative backend code, you define your routes, databases, schemas, and AI workflows as atomic, interconnected YAML documents. Telo takes those manifests and runs them.
+
+Built to be language-agnostic and infinitely extensible.
+
+```bash
+# Reconcile your manifest into a running backend
+$ telo ./examples/hello-api
+
+{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
+```
+
+## Why use Telo?
+
+- **Open Standards:** Built on YAML, JSON Schema, and CEL — no proprietary DSL.
+- **Static Analysis:** CEL type checking, reference validation, and IDE diagnostics catch errors before runtime.
+- **Micro-Kernel Architecture:** Telo itself knows nothing about HTTP or SQL. Everything is a module you import, scope, and compose with typed variable and secret contracts.
+- **Language Agnostic:** Available as a Node.js runtime today, with a shared YAML runtime contract that allows for future Rust or Go implementations without changing your manifests.
+
+## What It Does
+
+- **Loads** YAML resources and compiles CEL expressions (`${{ }}`) into an in-memory registry.
+- **Resolves** resource dependencies via a multi-pass init loop, handling ordering automatically.
+- **Indexes** resources by Kind and Name for constant-time lookup.
+- **Dispatches** execution to the controller that owns each Kind.
+
+## Example manifest
+
+See [examples/](./examples/) for a list of working applications.
+
+## Status
+
+Telo is under **active development**. The core runtime, module system, and standard library are functional, but the API surface — including YAML shapes — may change without notice. Not yet recommended for production use.
+
+## The Meaning of Telo
+
+The name Telo is derived from the Greek root Telos - meaning the "end goal", "purpose", or "final state". That is exactly the philosophy behind this runtime. In standard imperative programming, you have to write thousands of lines of code to tell a server exactly how to start. With Telo, you simply declare your desired final state.
+
+You define the end state. Telo makes it real.
+
+## Philosophy
+
+Modern platforms often spend disproportionate effort on technical mechanics-wiring frameworks, managing infrastructure, and negotiating toolchains-while the original business problem gets delayed or diluted. Telo pushes in the opposite direction: it treats kernel execution as a stable, predictable host so teams can concentrate on the **business logic and outcomes** instead of the plumbing.
+
+By separating "what the system should do" from "how it is hosted", the runtime reduces friction for domain‑level changes. Teams can move faster on product requirements, experiment more safely, and keep conversations centered on value delivered rather than implementation trivia.
+
+Telo also aims to **join forces across all programming language communities**, so the best ideas, patterns, and implementations can converge into a shared kernel truth without forcing everyone into a single stack.
+
+YAML also makes the system more **AI‑friendly** than traditional programming languages: it is explicit, structured, and easier for tools to generate, review, and transform without losing intent.
+
+## Modularity
+
+Telo is built around **modules** that own specific resource kinds. A module is loaded from a manifest, declares which kinds it implements, and then receives only the resources of those kinds. This keeps concerns isolated and lets teams compose systems from focused building blocks rather than monolithic services.
+
+At kernel execution time, execution is always routed by **Kind.Name**. The kernel resolves the Kind to its owning module and hands off execution. Modules can call back into the kernel to execute other resources, enabling composition without tight coupling.
+
+## Architecture
+
+The architecture is inspired by Kubernetes-style manifests: declarative resources, explicit kinds, and a control plane that routes work based on those definitions.
+Those manifests were taken to the next level by allowing them to run inside a standalone runtime host.
+
+## See more at
+
+- [Telo Kernel](./kernel/README.md)
+- [Telo SDK for module authors](sdk/README.md)
+- [Modules](modules/README.md)
+
+## License
+
+See [LICENSE](https://github.com/telorun/telo/blob/main/LICENSE).
+
+## Contribution Note
+
+By contributing, you agree that code and examples in this repository may be translated or re‑implemented in other programming languages (including by AI systems) to support the project’s polyglot goals.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { resolveShellHost } from "./shell-host-ref.js";
+export type { ShellHost, ExecutionHandle, StreamPart, BufferedResult, RunOptions, } from "./shell-host.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { resolveShellHost } from "./shell-host-ref.js";

package/dist/local-host-controller.d.ts

@@ -0,0 +1,23 @@
+import type { InvokeContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { ExecutionHandle, RunOptions, ShellHost } from "./shell-host.js";
+interface LocalHostManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    cwd?: string;
+    shell?: string;
+    env?: Record<string, string>;
+}
+declare class LocalShellHost implements ShellHost, ResourceInstance {
+    private readonly cwd;
+    private readonly shell;
+    private readonly baseEnv;
+    private readonly hostEnv;
+    constructor(cwd: string, shell: string, baseEnv: Record<string, string>, hostEnv: Record<string, string>);
+    snapshot(): Record<string, unknown>;
+    exec(command: string, options: RunOptions, ctx?: InvokeContext): ExecutionHandle;
+}
+export declare function register(): void;
+export declare function create(resource: LocalHostManifest, ctx: ResourceContext): Promise<LocalShellHost>;
+export {};

package/dist/local-host-controller.js

@@ -0,0 +1,246 @@
+import { spawn } from "node:child_process";
+/** Filter the kernel-sanctioned host env (`ctx.env`) down to defined entries. */
+function toEnvRecord(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (typeof value === "string")
+            out[key] = value;
+    }
+    return out;
+}
+function defaultShell(hostEnv) {
+    if (process.platform === "win32")
+        return hostEnv.ComSpec ?? "cmd.exe";
+    return "/bin/sh";
+}
+function shellInvocation(shell, command) {
+    if (process.platform === "win32")
+        return { file: shell, args: ["/d", "/s", "/c", command] };
+    return { file: shell, args: ["-c", command] };
+}
+/** Spawn the shell as its own process-group leader (POSIX) so the whole tree
+ *  can be torn down together. Without this, killing the shell orphans any
+ *  grandchild it spawned (a `sleep`, a dev server), which also keeps the stdout
+ *  pipe open so `close` never fires. */
+function spawnChild(spec) {
+    return spawn(spec.file, spec.args, {
+        cwd: spec.cwd,
+        env: spec.env,
+        detached: process.platform !== "win32",
+    });
+}
+/** Kill the child's entire process group (POSIX) / process (Windows). No-op if
+ *  it has already exited. */
+function killChild(child) {
+    if (child.pid === undefined || child.exitCode !== null || child.signalCode !== null)
+        return;
+    try {
+        if (process.platform === "win32")
+            child.kill("SIGKILL");
+        else
+            process.kill(-child.pid, "SIGKILL");
+    }
+    catch {
+        // ESRCH — the process group is already gone.
+    }
+}
+function writeStdin(child, stdin) {
+    if (!child.stdin)
+        return;
+    // A child that doesn't read stdin (or exits early) makes writes/`end()` emit
+    // EPIPE on the writable; with no listener Node escalates to an
+    // uncaughtException and tears the kernel down. EPIPE here is benign — the
+    // command's outcome is decided by its exit code — so absorb stdin errors.
+    child.stdin.on("error", () => { });
+    if (stdin !== undefined)
+        child.stdin.write(stdin);
+    child.stdin.end();
+}
+function spawnError(err, spec) {
+    if (err.code === "ENOENT")
+        return new Error(`Shell: interpreter not found: ${spec.file}`);
+    return new Error(`Shell: failed to run command (${err.code ?? err.message}): ${spec.command}`);
+}
+function runBuffered(spec) {
+    return new Promise((resolve, reject) => {
+        const child = spawnChild(spec);
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let cancelled = false;
+        const timer = spec.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                killChild(child);
+            }, spec.timeoutMs)
+            : undefined;
+        timer?.unref?.();
+        const onAbort = () => {
+            cancelled = true;
+            killChild(child);
+        };
+        if (spec.signal?.aborted)
+            onAbort();
+        else
+            spec.signal?.addEventListener("abort", onAbort, { once: true });
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            spec.signal?.removeEventListener("abort", onAbort);
+        };
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (d) => {
+            stdout += d;
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (d) => {
+            stderr += d;
+        });
+        child.on("error", (err) => {
+            cleanup();
+            reject(spawnError(err, spec));
+        });
+        child.on("close", (code, signal) => {
+            cleanup();
+            if (timedOut) {
+                reject(new Error(`Shell command timed out after ${spec.timeoutMs}ms: ${spec.command}`));
+                return;
+            }
+            if (cancelled) {
+                reject(new Error(`Shell command cancelled: ${spec.command}`));
+                return;
+            }
+            if (signal) {
+                reject(new Error(`Shell command terminated by signal ${signal}: ${spec.command}`));
+                return;
+            }
+            resolve({ stdout, stderr, exitCode: code ?? 0 });
+        });
+        writeStdin(child, spec.stdin);
+    });
+}
+function runStream(spec) {
+    return {
+        async *[Symbol.asyncIterator]() {
+            const child = spawnChild(spec);
+            const queue = [];
+            let finished = false;
+            let wake = null;
+            const wakeUp = () => {
+                if (wake) {
+                    const w = wake;
+                    wake = null;
+                    w();
+                }
+            };
+            const push = (part) => {
+                queue.push(part);
+                // Backpressure: pause the source streams while output is buffered; the
+                // consumer resumes them after it drains the queue, bounding memory.
+                child.stdout?.pause();
+                child.stderr?.pause();
+                wakeUp();
+            };
+            let timedOut = false;
+            let cancelled = false;
+            const timer = spec.timeoutMs
+                ? setTimeout(() => {
+                    timedOut = true;
+                    killChild(child);
+                }, spec.timeoutMs)
+                : undefined;
+            timer?.unref?.();
+            const onAbort = () => {
+                cancelled = true;
+                killChild(child);
+            };
+            if (spec.signal?.aborted)
+                onAbort();
+            else
+                spec.signal?.addEventListener("abort", onAbort, { once: true });
+            child.stdout?.setEncoding("utf8");
+            child.stdout?.on("data", (d) => push({ type: "stdout", chunk: d }));
+            child.stderr?.setEncoding("utf8");
+            child.stderr?.on("data", (d) => push({ type: "stderr", chunk: d }));
+            child.on("error", (err) => {
+                push({ type: "error", error: { message: err.message, code: err.code } });
+                finished = true;
+                wakeUp();
+            });
+            child.on("close", (code, signal) => {
+                if (timedOut) {
+                    push({ type: "error", error: { message: `Shell command timed out after ${spec.timeoutMs}ms`, code: "ETIMEDOUT" } });
+                }
+                else if (cancelled) {
+                    push({ type: "error", error: { message: "Shell command cancelled", code: "ECANCELLED" } });
+                }
+                else {
+                    push({ type: "exit", exitCode: code ?? 0, signal: signal ?? null });
+                }
+                finished = true;
+                wakeUp();
+            });
+            writeStdin(child, spec.stdin);
+            try {
+                while (true) {
+                    while (queue.length)
+                        yield queue.shift();
+                    if (finished)
+                        return;
+                    // Drained — resume the source and wait for the next record.
+                    child.stdout?.resume();
+                    child.stderr?.resume();
+                    await new Promise((r) => {
+                        wake = r;
+                    });
+                }
+            }
+            finally {
+                // Early termination (consumer break/return, a downstream throw, the
+                // enclosing sequence failing) lands here without `close` having fired —
+                // tear down the whole process group and clear timer/abort listener.
+                if (timer)
+                    clearTimeout(timer);
+                spec.signal?.removeEventListener("abort", onAbort);
+                killChild(child);
+            }
+        },
+    };
+}
+class LocalShellHost {
+    cwd;
+    shell;
+    baseEnv;
+    hostEnv;
+    constructor(cwd, shell, baseEnv, hostEnv) {
+        this.cwd = cwd;
+        this.shell = shell;
+        this.baseEnv = baseEnv;
+        this.hostEnv = hostEnv;
+    }
+    snapshot() {
+        return {};
+    }
+    exec(command, options, ctx) {
+        const { file, args } = shellInvocation(this.shell, command);
+        const spec = {
+            file,
+            args,
+            cwd: this.cwd,
+            env: { ...this.hostEnv, ...this.baseEnv, ...(options.env ?? {}) },
+            signal: ctx?.cancellation.signal,
+            timeoutMs: options.timeoutMs,
+            stdin: options.stdin,
+            command,
+        };
+        return {
+            buffered: () => runBuffered(spec),
+            stream: () => runStream(spec),
+        };
+    }
+}
+export function register() { }
+export async function create(resource, ctx) {
+    const hostEnv = toEnvRecord(ctx.env);
+    return new LocalShellHost(resource.cwd ?? ".", resource.shell ?? defaultShell(hostEnv), resource.env ?? {}, hostEnv);
+}

package/dist/shell-command-controller.d.ts

@@ -0,0 +1,28 @@
+import type { InvokeContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { BufferedResult, ShellHost } from "./shell-host.js";
+interface HostRef {
+    name: string;
+    alias?: string;
+}
+interface ShellCommandManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    host?: ShellHost | HostRef;
+}
+interface CommandInput {
+    command: string;
+    env?: Record<string, string>;
+    stdin?: string;
+    timeoutMs?: number;
+}
+declare class ShellCommandResource implements ResourceInstance {
+    private readonly manifest;
+    private readonly ctx;
+    constructor(manifest: ShellCommandManifest, ctx: ResourceContext);
+    invoke(input: CommandInput, ctx?: InvokeContext): Promise<BufferedResult>;
+}
+export declare function register(): void;
+export declare function create(resource: ShellCommandManifest, ctx: ResourceContext): Promise<ShellCommandResource>;
+export {};

package/dist/shell-command-controller.js

@@ -0,0 +1,26 @@
+import { resolveShellHost } from "./shell-host-ref.js";
+function requireCommand(input) {
+    if (typeof input?.command !== "string" || input.command.length === 0) {
+        throw new Error("Shell.Command: 'command' input is required and must be a non-empty string");
+    }
+    return input.command;
+}
+class ShellCommandResource {
+    manifest;
+    ctx;
+    constructor(manifest, ctx) {
+        this.manifest = manifest;
+        this.ctx = ctx;
+    }
+    async invoke(input, ctx) {
+        const host = resolveShellHost(this.manifest.host, this.ctx);
+        const command = requireCommand(input);
+        return host
+            .exec(command, { env: input.env, stdin: input.stdin, timeoutMs: input.timeoutMs }, ctx)
+            .buffered();
+    }
+}
+export function register() { }
+export async function create(resource, ctx) {
+    return new ShellCommandResource(resource, ctx);
+}

package/dist/shell-command-stream-controller.d.ts

@@ -0,0 +1,30 @@
+import { Stream, type InvokeContext, type ResourceContext, type ResourceInstance } from "@telorun/sdk";
+import type { ShellHost, StreamPart } from "./shell-host.js";
+interface HostRef {
+    name: string;
+    alias?: string;
+}
+interface ShellCommandStreamManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    host?: ShellHost | HostRef;
+}
+interface CommandInput {
+    command: string;
+    env?: Record<string, string>;
+    stdin?: string;
+    timeoutMs?: number;
+}
+declare class ShellCommandStreamResource implements ResourceInstance {
+    private readonly manifest;
+    private readonly ctx;
+    constructor(manifest: ShellCommandStreamManifest, ctx: ResourceContext);
+    invoke(input: CommandInput, ctx?: InvokeContext): Promise<{
+        output: Stream<StreamPart>;
+    }>;
+}
+export declare function register(): void;
+export declare function create(resource: ShellCommandStreamManifest, ctx: ResourceContext): Promise<ShellCommandStreamResource>;
+export {};

package/dist/shell-command-stream-controller.js

@@ -0,0 +1,28 @@
+import { Stream } from "@telorun/sdk";
+import { resolveShellHost } from "./shell-host-ref.js";
+function requireCommand(input) {
+    if (typeof input?.command !== "string" || input.command.length === 0) {
+        throw new Error("Shell.CommandStream: 'command' input is required and must be a non-empty string");
+    }
+    return input.command;
+}
+class ShellCommandStreamResource {
+    manifest;
+    ctx;
+    constructor(manifest, ctx) {
+        this.manifest = manifest;
+        this.ctx = ctx;
+    }
+    async invoke(input, ctx) {
+        const host = resolveShellHost(this.manifest.host, this.ctx);
+        const command = requireCommand(input);
+        const iterable = host
+            .exec(command, { env: input.env, stdin: input.stdin, timeoutMs: input.timeoutMs }, ctx)
+            .stream();
+        return { output: new Stream(iterable) };
+    }
+}
+export function register() { }
+export async function create(resource, ctx) {
+    return new ShellCommandStreamResource(resource, ctx);
+}

package/dist/shell-host-ref.d.ts

@@ -0,0 +1,15 @@
+import type { ResourceContext } from "@telorun/sdk";
+import type { ShellHost } from "./shell-host.js";
+interface HostRef {
+    name: string;
+    alias?: string;
+}
+/**
+ * Resolve the `host` field of a Shell operation to a live `Shell.Host`. The
+ * value is either the Phase-5-injected instance or — for a cross-module
+ * `!ref Alias.host` reached through a nested library — the raw `{name, alias}`
+ * ref, which must route through the import's exported scope. Mirrors
+ * `resolveSqlConnection`.
+ */
+export declare function resolveShellHost(value: ShellHost | HostRef | undefined, ctx: ResourceContext): ShellHost;
+export {};

package/dist/shell-host-ref.js

@@ -0,0 +1,34 @@
+function isShellHost(value) {
+    return typeof value?.exec === "function";
+}
+/**
+ * Resolve the `host` field of a Shell operation to a live `Shell.Host`. The
+ * value is either the Phase-5-injected instance or — for a cross-module
+ * `!ref Alias.host` reached through a nested library — the raw `{name, alias}`
+ * ref, which must route through the import's exported scope. Mirrors
+ * `resolveSqlConnection`.
+ */
+export function resolveShellHost(value, ctx) {
+    if (!value) {
+        throw new Error("Shell: 'host' is required");
+    }
+    if (isShellHost(value)) {
+        return value;
+    }
+    const ref = value;
+    if (typeof ref.name !== "string") {
+        throw new Error("Shell: invalid host reference");
+    }
+    if (ref.alias && ref.alias !== "Self") {
+        const instance = ctx.moduleContext.resolveImportedInstance(ref.alias, ref.name);
+        if (!isShellHost(instance)) {
+            throw new Error(`Shell: host reference '${ref.alias}.${ref.name}' did not resolve to a Shell.Host instance.`);
+        }
+        return instance;
+    }
+    const instance = ctx.moduleContext.getInstance(ref.name);
+    if (!isShellHost(instance)) {
+        throw new Error(`Shell: host reference '${ref.name}' did not resolve to a Shell.Host instance.`);
+    }
+    return instance;
+}

package/dist/shell-host.d.ts

@@ -0,0 +1,56 @@
+import type { InvokeContext } from "@telorun/sdk";
+/**
+ * The transport-neutral `Shell.Host` contract — the module's central seam.
+ * Every driver (the bundled local host, and future `shell-ssh` / Docker / k8s
+ * modules) implements `ShellHost`; the generic operations (`Shell.Command`,
+ * `Shell.CommandStream`) and the ref resolver depend only on this file, never
+ * on a concrete driver. Mirrors `sql`'s `sqlite-driver-interface.ts` split.
+ */
+/** One record in a `Shell.CommandStream` output stream. */
+export type StreamPart = {
+    type: "stdout";
+    chunk: string;
+} | {
+    type: "stderr";
+    chunk: string;
+} | {
+    type: "exit";
+    exitCode: number;
+    signal: string | null;
+} | {
+    type: "error";
+    error: {
+        message: string;
+        code?: string;
+    };
+};
+export interface BufferedResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface RunOptions {
+    /** Per-call environment overlay, merged over the host's base env. */
+    env?: Record<string, string>;
+    /** Written to the child's stdin, which is then closed. */
+    stdin?: string;
+    /** Kill the child and fail after this many milliseconds. */
+    timeoutMs?: number;
+}
+/**
+ * The execution primitive every driver implements. `exec` composes the command
+ * for its target and returns a lazy handle the operations consume either
+ * buffered (`Shell.Command`) or streamed (`Shell.CommandStream`) — exactly one
+ * per call. The host owns all composition (`<shell> -c <command>`, env merge,
+ * cwd) so the operations stay backend-agnostic. (Named `exec`, not `run`, to
+ * avoid the Runnable capability's reserved `run()`.)
+ */
+export interface ShellHost {
+    exec(command: string, options: RunOptions, ctx?: InvokeContext): ExecutionHandle;
+}
+export interface ExecutionHandle {
+    /** Spawn, collect all output, and resolve once the process exits. */
+    buffered(): Promise<BufferedResult>;
+    /** Spawn on iteration; yield stdout/stderr records then a terminal exit/error. */
+    stream(): AsyncIterable<StreamPart>;
+}

package/dist/shell-host.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@telorun/shell",
+  "version": "0.1.0",
+  "description": "Telo shell module - run shell commands behind a transport-neutral host abstraction.",
+  "keywords": [
+    "telo",
+    "shell",
+    "command",
+    "exec",
+    "process"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "modules/shell/nodejs"
+  },
+  "homepage": "https://github.com/telorun/telo#readme",
+  "bugs": {
+    "url": "https://github.com/telorun/telo/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./local-host": {
+      "types": "./dist/local-host-controller.d.ts",
+      "bun": "./src/local-host-controller.ts",
+      "import": "./dist/local-host-controller.js"
+    },
+    "./shell-command": {
+      "bun": "./src/shell-command-controller.ts",
+      "import": "./dist/shell-command-controller.js"
+    },
+    "./shell-command-stream": {
+      "bun": "./src/shell-command-stream-controller.ts",
+      "import": "./dist/shell-command-stream-controller.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "@telorun/sdk": "0.38.0"
+  },
+  "peerDependencies": {
+    "@telorun/sdk": "*"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { resolveShellHost } from "./shell-host-ref.js";
+export type {
+  ShellHost,
+  ExecutionHandle,
+  StreamPart,
+  BufferedResult,
+  RunOptions,
+} from "./shell-host.js";

package/src/local-host-controller.ts

@@ -0,0 +1,269 @@
+import type { InvokeContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { spawn, type ChildProcess } from "node:child_process";
+import type {
+  BufferedResult,
+  ExecutionHandle,
+  RunOptions,
+  ShellHost,
+  StreamPart,
+} from "./shell-host.js";
+
+interface SpawnSpec {
+  file: string;
+  args: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  stdin?: string;
+  command: string;
+}
+
+interface LocalHostManifest {
+  metadata: { name: string; module: string };
+  cwd?: string;
+  shell?: string;
+  env?: Record<string, string>;
+}
+
+/** Filter the kernel-sanctioned host env (`ctx.env`) down to defined entries. */
+function toEnvRecord(env: Record<string, string | undefined>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value === "string") out[key] = value;
+  }
+  return out;
+}
+
+function defaultShell(hostEnv: Record<string, string>): string {
+  if (process.platform === "win32") return hostEnv.ComSpec ?? "cmd.exe";
+  return "/bin/sh";
+}
+
+function shellInvocation(shell: string, command: string): { file: string; args: string[] } {
+  if (process.platform === "win32") return { file: shell, args: ["/d", "/s", "/c", command] };
+  return { file: shell, args: ["-c", command] };
+}
+
+/** Spawn the shell as its own process-group leader (POSIX) so the whole tree
+ *  can be torn down together. Without this, killing the shell orphans any
+ *  grandchild it spawned (a `sleep`, a dev server), which also keeps the stdout
+ *  pipe open so `close` never fires. */
+function spawnChild(spec: SpawnSpec): ChildProcess {
+  return spawn(spec.file, spec.args, {
+    cwd: spec.cwd,
+    env: spec.env,
+    detached: process.platform !== "win32",
+  });
+}
+
+/** Kill the child's entire process group (POSIX) / process (Windows). No-op if
+ *  it has already exited. */
+function killChild(child: ChildProcess): void {
+  if (child.pid === undefined || child.exitCode !== null || child.signalCode !== null) return;
+  try {
+    if (process.platform === "win32") child.kill("SIGKILL");
+    else process.kill(-child.pid, "SIGKILL");
+  } catch {
+    // ESRCH — the process group is already gone.
+  }
+}
+
+function writeStdin(child: ChildProcess, stdin?: string): void {
+  if (!child.stdin) return;
+  // A child that doesn't read stdin (or exits early) makes writes/`end()` emit
+  // EPIPE on the writable; with no listener Node escalates to an
+  // uncaughtException and tears the kernel down. EPIPE here is benign — the
+  // command's outcome is decided by its exit code — so absorb stdin errors.
+  child.stdin.on("error", () => {});
+  if (stdin !== undefined) child.stdin.write(stdin);
+  child.stdin.end();
+}
+
+function spawnError(err: NodeJS.ErrnoException, spec: SpawnSpec): Error {
+  if (err.code === "ENOENT") return new Error(`Shell: interpreter not found: ${spec.file}`);
+  return new Error(`Shell: failed to run command (${err.code ?? err.message}): ${spec.command}`);
+}
+
+function runBuffered(spec: SpawnSpec): Promise<BufferedResult> {
+  return new Promise<BufferedResult>((resolve, reject) => {
+    const child = spawnChild(spec);
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let cancelled = false;
+    const timer = spec.timeoutMs
+      ? setTimeout(() => {
+          timedOut = true;
+          killChild(child);
+        }, spec.timeoutMs)
+      : undefined;
+    timer?.unref?.();
+    const onAbort = () => {
+      cancelled = true;
+      killChild(child);
+    };
+    if (spec.signal?.aborted) onAbort();
+    else spec.signal?.addEventListener("abort", onAbort, { once: true });
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      spec.signal?.removeEventListener("abort", onAbort);
+    };
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (d: string) => {
+      stdout += d;
+    });
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (d: string) => {
+      stderr += d;
+    });
+    child.on("error", (err: NodeJS.ErrnoException) => {
+      cleanup();
+      reject(spawnError(err, spec));
+    });
+    child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
+      cleanup();
+      if (timedOut) {
+        reject(new Error(`Shell command timed out after ${spec.timeoutMs}ms: ${spec.command}`));
+        return;
+      }
+      if (cancelled) {
+        reject(new Error(`Shell command cancelled: ${spec.command}`));
+        return;
+      }
+      if (signal) {
+        reject(new Error(`Shell command terminated by signal ${signal}: ${spec.command}`));
+        return;
+      }
+      resolve({ stdout, stderr, exitCode: code ?? 0 });
+    });
+    writeStdin(child, spec.stdin);
+  });
+}
+
+function runStream(spec: SpawnSpec): AsyncIterable<StreamPart> {
+  return {
+    async *[Symbol.asyncIterator]() {
+      const child = spawnChild(spec);
+      const queue: StreamPart[] = [];
+      let finished = false;
+      let wake: (() => void) | null = null;
+      const wakeUp = () => {
+        if (wake) {
+          const w = wake;
+          wake = null;
+          w();
+        }
+      };
+      const push = (part: StreamPart) => {
+        queue.push(part);
+        // Backpressure: pause the source streams while output is buffered; the
+        // consumer resumes them after it drains the queue, bounding memory.
+        child.stdout?.pause();
+        child.stderr?.pause();
+        wakeUp();
+      };
+      let timedOut = false;
+      let cancelled = false;
+      const timer = spec.timeoutMs
+        ? setTimeout(() => {
+            timedOut = true;
+            killChild(child);
+          }, spec.timeoutMs)
+        : undefined;
+      timer?.unref?.();
+      const onAbort = () => {
+        cancelled = true;
+        killChild(child);
+      };
+      if (spec.signal?.aborted) onAbort();
+      else spec.signal?.addEventListener("abort", onAbort, { once: true });
+      child.stdout?.setEncoding("utf8");
+      child.stdout?.on("data", (d: string) => push({ type: "stdout", chunk: d }));
+      child.stderr?.setEncoding("utf8");
+      child.stderr?.on("data", (d: string) => push({ type: "stderr", chunk: d }));
+      child.on("error", (err: NodeJS.ErrnoException) => {
+        push({ type: "error", error: { message: err.message, code: err.code } });
+        finished = true;
+        wakeUp();
+      });
+      child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
+        if (timedOut) {
+          push({ type: "error", error: { message: `Shell command timed out after ${spec.timeoutMs}ms`, code: "ETIMEDOUT" } });
+        } else if (cancelled) {
+          push({ type: "error", error: { message: "Shell command cancelled", code: "ECANCELLED" } });
+        } else {
+          push({ type: "exit", exitCode: code ?? 0, signal: signal ?? null });
+        }
+        finished = true;
+        wakeUp();
+      });
+      writeStdin(child, spec.stdin);
+      try {
+        while (true) {
+          while (queue.length) yield queue.shift() as StreamPart;
+          if (finished) return;
+          // Drained — resume the source and wait for the next record.
+          child.stdout?.resume();
+          child.stderr?.resume();
+          await new Promise<void>((r) => {
+            wake = r;
+          });
+        }
+      } finally {
+        // Early termination (consumer break/return, a downstream throw, the
+        // enclosing sequence failing) lands here without `close` having fired —
+        // tear down the whole process group and clear timer/abort listener.
+        if (timer) clearTimeout(timer);
+        spec.signal?.removeEventListener("abort", onAbort);
+        killChild(child);
+      }
+    },
+  };
+}
+
+class LocalShellHost implements ShellHost, ResourceInstance {
+  constructor(
+    private readonly cwd: string,
+    private readonly shell: string,
+    private readonly baseEnv: Record<string, string>,
+    private readonly hostEnv: Record<string, string>,
+  ) {}
+
+  snapshot(): Record<string, unknown> {
+    return {};
+  }
+
+  exec(command: string, options: RunOptions, ctx?: InvokeContext): ExecutionHandle {
+    const { file, args } = shellInvocation(this.shell, command);
+    const spec: SpawnSpec = {
+      file,
+      args,
+      cwd: this.cwd,
+      env: { ...this.hostEnv, ...this.baseEnv, ...(options.env ?? {}) },
+      signal: ctx?.cancellation.signal,
+      timeoutMs: options.timeoutMs,
+      stdin: options.stdin,
+      command,
+    };
+    return {
+      buffered: () => runBuffered(spec),
+      stream: () => runStream(spec),
+    };
+  }
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: LocalHostManifest,
+  ctx: ResourceContext,
+): Promise<LocalShellHost> {
+  const hostEnv = toEnvRecord(ctx.env);
+  return new LocalShellHost(
+    resource.cwd ?? ".",
+    resource.shell ?? defaultShell(hostEnv),
+    resource.env ?? {},
+    hostEnv,
+  );
+}

package/src/shell-command-controller.ts

@@ -0,0 +1,51 @@
+import type { InvokeContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { BufferedResult, ShellHost } from "./shell-host.js";
+import { resolveShellHost } from "./shell-host-ref.js";
+
+interface HostRef {
+  name: string;
+  alias?: string;
+}
+
+interface ShellCommandManifest {
+  metadata: { name: string; module: string };
+  host?: ShellHost | HostRef;
+}
+
+interface CommandInput {
+  command: string;
+  env?: Record<string, string>;
+  stdin?: string;
+  timeoutMs?: number;
+}
+
+function requireCommand(input: CommandInput): string {
+  if (typeof input?.command !== "string" || input.command.length === 0) {
+    throw new Error("Shell.Command: 'command' input is required and must be a non-empty string");
+  }
+  return input.command;
+}
+
+class ShellCommandResource implements ResourceInstance {
+  constructor(
+    private readonly manifest: ShellCommandManifest,
+    private readonly ctx: ResourceContext,
+  ) {}
+
+  async invoke(input: CommandInput, ctx?: InvokeContext): Promise<BufferedResult> {
+    const host = resolveShellHost(this.manifest.host, this.ctx);
+    const command = requireCommand(input);
+    return host
+      .exec(command, { env: input.env, stdin: input.stdin, timeoutMs: input.timeoutMs }, ctx)
+      .buffered();
+  }
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: ShellCommandManifest,
+  ctx: ResourceContext,
+): Promise<ShellCommandResource> {
+  return new ShellCommandResource(resource, ctx);
+}

package/src/shell-command-stream-controller.ts

@@ -0,0 +1,52 @@
+import { Stream, type InvokeContext, type ResourceContext, type ResourceInstance } from "@telorun/sdk";
+import type { ShellHost, StreamPart } from "./shell-host.js";
+import { resolveShellHost } from "./shell-host-ref.js";
+
+interface HostRef {
+  name: string;
+  alias?: string;
+}
+
+interface ShellCommandStreamManifest {
+  metadata: { name: string; module: string };
+  host?: ShellHost | HostRef;
+}
+
+interface CommandInput {
+  command: string;
+  env?: Record<string, string>;
+  stdin?: string;
+  timeoutMs?: number;
+}
+
+function requireCommand(input: CommandInput): string {
+  if (typeof input?.command !== "string" || input.command.length === 0) {
+    throw new Error("Shell.CommandStream: 'command' input is required and must be a non-empty string");
+  }
+  return input.command;
+}
+
+class ShellCommandStreamResource implements ResourceInstance {
+  constructor(
+    private readonly manifest: ShellCommandStreamManifest,
+    private readonly ctx: ResourceContext,
+  ) {}
+
+  async invoke(input: CommandInput, ctx?: InvokeContext): Promise<{ output: Stream<StreamPart> }> {
+    const host = resolveShellHost(this.manifest.host, this.ctx);
+    const command = requireCommand(input);
+    const iterable = host
+      .exec(command, { env: input.env, stdin: input.stdin, timeoutMs: input.timeoutMs }, ctx)
+      .stream();
+    return { output: new Stream(iterable) };
+  }
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: ShellCommandStreamManifest,
+  ctx: ResourceContext,
+): Promise<ShellCommandStreamResource> {
+  return new ShellCommandStreamResource(resource, ctx);
+}

package/src/shell-host-ref.ts

@@ -0,0 +1,48 @@
+import type { ResourceContext } from "@telorun/sdk";
+import type { ShellHost } from "./shell-host.js";
+
+interface HostRef {
+  name: string;
+  alias?: string;
+}
+
+function isShellHost(value: unknown): value is ShellHost {
+  return typeof (value as ShellHost | undefined)?.exec === "function";
+}
+
+/**
+ * Resolve the `host` field of a Shell operation to a live `Shell.Host`. The
+ * value is either the Phase-5-injected instance or — for a cross-module
+ * `!ref Alias.host` reached through a nested library — the raw `{name, alias}`
+ * ref, which must route through the import's exported scope. Mirrors
+ * `resolveSqlConnection`.
+ */
+export function resolveShellHost(value: ShellHost | HostRef | undefined, ctx: ResourceContext): ShellHost {
+  if (!value) {
+    throw new Error("Shell: 'host' is required");
+  }
+  if (isShellHost(value)) {
+    return value;
+  }
+
+  const ref = value as HostRef;
+  if (typeof ref.name !== "string") {
+    throw new Error("Shell: invalid host reference");
+  }
+
+  if (ref.alias && ref.alias !== "Self") {
+    const instance = ctx.moduleContext.resolveImportedInstance(ref.alias, ref.name);
+    if (!isShellHost(instance)) {
+      throw new Error(
+        `Shell: host reference '${ref.alias}.${ref.name}' did not resolve to a Shell.Host instance.`,
+      );
+    }
+    return instance;
+  }
+
+  const instance = ctx.moduleContext.getInstance(ref.name);
+  if (!isShellHost(instance)) {
+    throw new Error(`Shell: host reference '${ref.name}' did not resolve to a Shell.Host instance.`);
+  }
+  return instance;
+}

package/src/shell-host.ts

@@ -0,0 +1,50 @@
+import type { InvokeContext } from "@telorun/sdk";
+
+/**
+ * The transport-neutral `Shell.Host` contract — the module's central seam.
+ * Every driver (the bundled local host, and future `shell-ssh` / Docker / k8s
+ * modules) implements `ShellHost`; the generic operations (`Shell.Command`,
+ * `Shell.CommandStream`) and the ref resolver depend only on this file, never
+ * on a concrete driver. Mirrors `sql`'s `sqlite-driver-interface.ts` split.
+ */
+
+/** One record in a `Shell.CommandStream` output stream. */
+export type StreamPart =
+  | { type: "stdout"; chunk: string }
+  | { type: "stderr"; chunk: string }
+  | { type: "exit"; exitCode: number; signal: string | null }
+  | { type: "error"; error: { message: string; code?: string } };
+
+export interface BufferedResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface RunOptions {
+  /** Per-call environment overlay, merged over the host's base env. */
+  env?: Record<string, string>;
+  /** Written to the child's stdin, which is then closed. */
+  stdin?: string;
+  /** Kill the child and fail after this many milliseconds. */
+  timeoutMs?: number;
+}
+
+/**
+ * The execution primitive every driver implements. `exec` composes the command
+ * for its target and returns a lazy handle the operations consume either
+ * buffered (`Shell.Command`) or streamed (`Shell.CommandStream`) — exactly one
+ * per call. The host owns all composition (`<shell> -c <command>`, env merge,
+ * cwd) so the operations stay backend-agnostic. (Named `exec`, not `run`, to
+ * avoid the Runnable capability's reserved `run()`.)
+ */
+export interface ShellHost {
+  exec(command: string, options: RunOptions, ctx?: InvokeContext): ExecutionHandle;
+}
+
+export interface ExecutionHandle {
+  /** Spawn, collect all output, and resolve once the process exits. */
+  buffered(): Promise<BufferedResult>;
+  /** Spawn on iteration; yield stdout/stderr records then a terminal exit/error. */
+  stream(): AsyncIterable<StreamPart>;
+}