v2.0.2

.smartconfig.json

@@ -0,0 +1,24 @@
+{
+  "npmts": {},
+  "@git.zone/cli": {
+    "projectType": "npm",
+    "module": {
+      "githost": "gitlab.com",
+      "gitscope": "gitzone",
+      "gitrepo": "tsrun",
+      "description": "run typescript programs efficiently",
+      "npmPackagename": "@git.zone/tsrun",
+      "license": "MIT"
+    },
+    "release": {
+      "registries": [
+        "https://verdaccio.lossless.digital",
+        "https://registry.npmjs.org"
+      ],
+      "accessLevel": "public"
+    }
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": []
+  }
+}

.vscode/settings.json

@@ -1,7 +1,7 @@
 {
   "json.schemas": [
     {
-      "fileMatch": ["/npmextra.json"],
+      "fileMatch": ["/.smartconfig.json"],
       "schema": {
         "type": "object",
         "properties": {

changelog.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 2026-03-24 - 2.0.2 - fix(build)
+migrate package metadata to smartconfig and refresh build configuration
+
+- replace npmextra.json with .smartconfig.json and update published package files
+- remove the web build flag from the build script
+- refresh dependency versions and remove the unused node-fetch dev dependency
+- rewrite the README to reflect current CLI, API, and Node.js support
+
+## 2025-12-13 - 2.0.1 - fix(cli)
+Align package scope to @git.zone, bump dependency versions and remove obsolete pnpm workspace setting
+
+- Update runtime import in cli.ts.js from @gitzone/tsrun to @git.zone/tsrun
+- Change npm package name in npmextra.json to @git.zone/tsrun
+- Bump devDependencies and dependencies in package.json (@git.zone/tsbuild -> ^3.1.2, @push.rocks/smartcli -> ^4.0.19, @types/node -> ^25.0.1, @push.rocks/smartfile -> ^13.1.0, tsx -> ^4.21.0)
+- Remove onlyBuiltDependencies entry from pnpm-workspace.yaml
+- Ensure commitinfo metadata (ts/00_commitinfo_data.ts) and package.json remain aligned with @git.zone/tsrun
+
+## 2025-11-17 - 2.0.0 - BREAKING CHANGE(tsconfig)
+Remove experimentalDecorators and useDefineForClassFields from tsconfig.json
+
+- tsconfig.json: removed compilerOptions.experimentalDecorators — decorator support is no longer enabled by default. Projects using decorators must enable experimentalDecorators in their own tsconfig.
+- tsconfig.json: removed compilerOptions.useDefineForClassFields — class field emit will follow TypeScript defaults, which may change runtime semantics for some classes.
+- This may break consumers relying on the previous compiler options; bumping the major version to reflect the potential breaking change.
+
+## 2025-10-17 - 1.6.2 - fix(ts/index)
+Use cli.js as the spawned CLI entry point instead of cli.child.js
+
+- Replace references to ../cli.child.js with ../cli.js in ts/index.ts (runInChildProcess and spawnPath) to ensure child processes spawn the correct CLI entry point.
+- This change fixes child process spawning failures caused by referencing a non-existent cli.child.js file.
+- Add local .claude/settings.local.json (local runner/editor permissions configuration).
+
+## 2025-10-17 - 1.6.1 - fix(plugins)
+Export child_process.spawn from plugins and use plugins.spawn in spawnPath to remove direct require and unify process spawning
+
+- Exported spawn from ts/plugins.ts so native child_process.spawn is available via the plugins module
+- Removed require('child_process') from ts/index.ts and switched to plugins.spawn when spawning child processes in spawnPath
+- No public API changes; this unifies internal imports and fixes inconsistent spawn usage that could cause runtime issues
+
+## 2025-10-17 - 1.6.0 - feat(core)
+Add spawnPath child-process API with timeout/abort/terminate support, export native types, and expand README
+
+- Implement spawnPath(filePath, fromFileUrl?, options?) in ts/index.ts producing an ITsrunChildProcess with childProcess, stdout, stderr, exitCode, kill() and terminate()
+- Introduce ISpawnOptions (cwd, env, args, stdio, timeout, signal) and ITsrunChildProcess interfaces for robust process control
+- Handle timeouts (auto SIGTERM), AbortSignal cancellation, and graceful terminate() (SIGTERM then SIGKILL after 5s)
+- Export Node types ChildProcess and Readable from ts/plugins.ts for improved typings
+- Greatly expand README: add badges, table of contents, detailed API docs and examples for runPath, runCli and spawnPath, and troubleshooting guidance
+- Add local .claude/settings.local.json (environment/settings file)
+
+## 2025-10-16 - 1.5.0 - feat(core)
+Add cwd option and child-process execution for custom working directory; implement signal-forwarding child runner; update docs and bump package version to 1.4.0
+
+- Introduce IRunOptions with cwd support to runPath/runCli
+- When cwd is provided, runCli now spawns a child process (runInChildProcess) to execute the script in the specified working directory
+- runInChildProcess preserves node execArgv, inherits env and stdio, forwards signals (SIGINT, SIGTERM, SIGHUP) and propagates child exit codes/signals
+- Update README with documentation and examples for running scripts with a custom working directory and parallel execution
+- Bump package version to 1.4.0
+
 ## 2025-10-13 - 1.3.4 - fix(docs)
 Update README with expanded docs and examples; add pnpm and CI tooling configs
 

cli.ts.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 process.env.CLI_CALL = 'true';
 
-import * as tsrun from '@gitzone/tsrun';
+import * as tsrun from '@git.zone/tsrun';
 tsrun.runPath('./cli.child.js', import.meta.url);

npmextra.json

@@ -1,18 +0,0 @@
-{
-  "npmts": {},
-  "npmci": {
-    "npmGlobalTools": [],
-    "npmAccessLevel": "public"
-  },
-  "gitzone": {
-    "projectType": "npm",
-    "module": {
-      "githost": "gitlab.com",
-      "gitscope": "gitzone",
-      "gitrepo": "tsrun",
-      "description": "run typescript programs efficiently",
-      "npmPackagename": "@gitzone/tsrun",
-      "license": "MIT"
-    }
-  }
-}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git.zone/tsrun",
-  "version": "1.3.4",
+  "version": "2.0.2",
   "description": "run typescript programs efficiently",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
@@ -13,19 +13,18 @@
   "scripts": {
     "test": "(pnpm run build && node ./cli.js test/test.js sayhello)",
     "format": "(gitzone format)",
-    "build": "(tsbuild --web --allowimplicitany)",
+    "build": "(tsbuild --allowimplicitany)",
     "buildDocs": "tsdoc"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.1.80",
-    "@push.rocks/smartcli": "^4.0.11",
-    "@types/node": "^20.14.8",
-    "node-fetch": "^3.3.2"
+    "@git.zone/tsbuild": "^4.4.0",
+    "@push.rocks/smartcli": "^4.0.20",
+    "@types/node": "^25.5.0"
   },
   "dependencies": {
-    "@push.rocks/smartfile": "^11.0.21",
-    "@push.rocks/smartshell": "^3.0.5",
-    "tsx": "^4.19.2"
+    "@push.rocks/smartfile": "^13.1.2",
+    "@push.rocks/smartshell": "^3.3.8",
+    "tsx": "^4.21.0"
   },
   "private": false,
   "files": [
@@ -37,7 +36,7 @@
     "dist_ts_web/**/*",
     "assets/**/*",
     "cli.js",
-    "npmextra.json",
+    ".smartconfig.json",
     "readme.md"
   ],
   "browserslist": [

pnpm-workspace.yaml

@@ -1,2 +0,0 @@
-onlyBuiltDependencies:
-  - esbuild

readme.md

@@ -1,172 +1,345 @@
 # @git.zone/tsrun
 
-> Run TypeScript files instantly, without the compilation hassle ⚡
+[![npm version](https://img.shields.io/npm/v/@git.zone/tsrun.svg)](https://www.npmjs.com/package/@git.zone/tsrun)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-native-blue)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green)](https://nodejs.org/)
 
-Execute TypeScript programs on-the-fly with zero configuration. Perfect for scripts, prototyping, and development workflows.
+> Run TypeScript files instantly — no build step, no config, no friction ⚡
+
+Execute TypeScript programs on-the-fly with zero configuration. Whether you're writing quick scripts, prototyping ideas, or orchestrating complex multi-project workflows, tsrun gets out of your way and lets you focus on code.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Table of Contents
+
+- [What is tsrun?](#what-is-tsrun)
+- [Installation](#installation)
+- [CLI Usage](#-cli-usage)
+- [Programmatic API](#-programmatic-api)
+  - [runPath()](#runpath---simple-execution)
+  - [runCli()](#runcli---cli-mode)
+  - [spawnPath()](#spawnpath---advanced-process-control)
+- [API Quick Reference](#api-quick-reference)
+- [Features](#features)
+- [Common Use Cases](#common-use-cases)
+- [Troubleshooting](#troubleshooting)
+- [License and Legal Information](#license-and-legal-information)
 
 ## What is tsrun?
 
-**tsrun** is a lightweight TypeScript execution tool that lets you run `.ts` files directly—no build step required. It's like running JavaScript with `node`, but for TypeScript. Under the hood, tsrun uses [tsx](https://github.com/esbuild-kit/tsx) for lightning-fast execution while keeping your workflow simple and efficient.
+**tsrun** is a lightweight TypeScript execution tool that lets you run `.ts` files directly — just like running JavaScript with `node`, but for TypeScript. Under the hood, it uses [tsx](https://github.com/privatenumber/tsx) for lightning-fast transpilation, so there's no compilation step, no tsconfig fiddling, and no waiting around.
+
+It also doubles as a **programmatic library** with full process control — spawn TypeScript processes, capture their output, set timeouts, and cancel them with `AbortController`. Perfect for build scripts, task runners, and orchestration tools.
 
 ## Installation
 
-```bash
-npm install -g @git.zone/tsrun
-```
-
-Or as a project dependency:
+**Global** (recommended for CLI usage):
 
 ```bash
-npm install --save-dev @git.zone/tsrun
+pnpm install -g @git.zone/tsrun
 ```
 
-## Usage
+**As a project dependency** (for programmatic API):
 
-### 🚀 CLI Usage
+```bash
+pnpm install @git.zone/tsrun
+```
 
-Simply run any TypeScript file:
+## 🚀 CLI Usage
+
+Run any TypeScript file:
 
 ```bash
 tsrun myScript.ts
 ```
 
-Pass arguments to your script transparently:
+Arguments pass through transparently, just like `node`:
 
 ```bash
-tsrun myScript.ts --config production --verbose
+tsrun deploy.ts production --verbose --dry-run
 ```
 
-All arguments are passed through to your TypeScript program, just as if you were running it with `node`.
-
-### 💻 Programmatic API
-
-Import tsrun in your code for dynamic TypeScript execution:
-
-```typescript
-import { runPath, runCli } from '@git.zone/tsrun';
-
-// Run a TypeScript file from an absolute or relative path
-await runPath('./scripts/myScript.ts');
-
-// Run with path resolution relative to a file URL
-await runPath('./myScript.ts', import.meta.url);
-
-// Run in CLI mode programmatically (respects process.argv)
-await runCli('./myScript.ts');
-```
-
-## Features
-
-✨ **Zero Configuration** - Just point and shoot. No tsconfig tweaking required.
-
-⚡ **Fast Execution** - Powered by tsx for near-instant TypeScript execution.
-
-🔄 **Transparent Arguments** - Command line arguments pass through seamlessly to your scripts.
-
-📦 **Dual Interface** - Use as a CLI tool or import as a library in your code.
-
-🎯 **TypeScript Native** - Full TypeScript support with excellent IntelliSense.
-
-## Why tsrun?
-
-Sometimes you just want to run a TypeScript file without setting up a build pipeline, configuring webpack, or waiting for `tsc` to compile. That's where tsrun shines:
-
-- **Quick Scripts**: Write and run TypeScript scripts as easily as bash scripts
-- **Prototyping**: Test ideas without project setup overhead
-- **Development Workflows**: Integrate TypeScript execution into your tooling
-- **CI/CD**: Run TypeScript-based build scripts without pre-compilation
-
-## Examples
-
-### Simple Script
-
-```typescript
-// hello.ts
-console.log('Hello from TypeScript! 🎉');
-
-const greet = (name: string): string => {
-  return `Welcome, ${name}!`;
-};
-
-console.log(greet('Developer'));
-```
-
-Run it:
-
-```bash
-tsrun hello.ts
-# Output:
-# Hello from TypeScript! 🎉
-# Welcome, Developer!
-```
-
-### With Command Line Arguments
+Your script sees them in `process.argv` as expected:
 
 ```typescript
 // deploy.ts
-const environment = process.argv[2] || 'development';
+const env = process.argv[0];     // "production"
 const verbose = process.argv.includes('--verbose');
+const dryRun = process.argv.includes('--dry-run');
 
-console.log(`Deploying to ${environment}...`);
-if (verbose) {
-  console.log('Verbose mode enabled');
-}
+console.log(`Deploying to ${env}...`);
 ```
 
-Run it:
+## 💻 Programmatic API
 
-```bash
-tsrun deploy.ts production --verbose
-# Output:
-# Deploying to production...
-# Verbose mode enabled
-```
+tsrun exports three functions tailored for different execution needs.
 
-### Programmatic Execution
+### `runPath()` — Simple Execution
+
+Runs a TypeScript file and waits for it to complete. The simplest way to execute scripts programmatically.
 
 ```typescript
-// runner.ts
 import { runPath } from '@git.zone/tsrun';
 
-const scripts = [
-  './scripts/setup.ts',
-  './scripts/migrate.ts',
-  './scripts/seed.ts'
-];
+// Run a script (path relative to cwd)
+await runPath('./scripts/build.ts');
 
-for (const script of scripts) {
-  console.log(`Running ${script}...`);
-  await runPath(script, import.meta.url);
-  console.log(`✓ ${script} completed`);
+// Resolve path relative to the calling file
+await runPath('./build.ts', import.meta.url);
+
+// Run in a different working directory (spawns a child process)
+await runPath('./build.ts', import.meta.url, { cwd: '/path/to/project' });
+```
+
+**How it works:**
+- Without `cwd` — executes **in-process** using tsx's ESM loader (fast, zero overhead)
+- With `cwd` — spawns an **isolated child process** with the given working directory
+
+### `runCli()` — CLI Mode
+
+Runs with `process.argv` integration, as if the script were invoked from the command line. This is what the `tsrun` CLI binary uses internally.
+
+```typescript
+import { runCli } from '@git.zone/tsrun';
+
+// Uses process.argv for argument passing
+await runCli('./script.ts');
+
+// With custom working directory
+await runCli('./script.ts', { cwd: '/path/to/project' });
+```
+
+### `spawnPath()` — Advanced Process Control
+
+Returns immediately with a process handle, giving you full control over stdio, timeouts, and cancellation.
+
+```typescript
+import { spawnPath } from '@git.zone/tsrun';
+
+const proc = spawnPath('./task.ts', import.meta.url, {
+  timeout: 30000,                    // Kill after 30s
+  cwd: '/path/to/project',
+  env: { NODE_ENV: 'production' },   // Merged with process.env
+  args: ['--verbose'],               // Extra CLI args
+  stdio: 'pipe',                     // Default: capture stdout/stderr
+});
+
+// Stream stdout
+proc.stdout?.on('data', (chunk) => {
+  console.log(chunk.toString());
+});
+
+// Wait for exit
+const exitCode = await proc.exitCode;
+```
+
+**AbortController support:**
+
+```typescript
+const controller = new AbortController();
+const proc = spawnPath('./task.ts', import.meta.url, {
+  signal: controller.signal,
+});
+
+// Cancel from outside
+setTimeout(() => controller.abort(), 5000);
+
+try {
+  await proc.exitCode;
+} catch (err) {
+  console.log('Process was cancelled');
 }
 ```
 
-## Package Information
+**Graceful termination:**
 
-- **npmjs**: [@git.zone/tsrun](https://www.npmjs.com/package/@git.zone/tsrun)
-- **Source**: [git.zone](https://git.zone/lossless/tsrun) | [GitLab Mirror](https://gitlab.com/gitzone/tsrun) | [GitHub Mirror](https://github.com/gitzone/tsrun)
-- **Documentation**: [TypeDoc](https://gitzone.gitlab.io/tsrun/)
+```typescript
+const proc = spawnPath('./server.ts', import.meta.url);
 
-## Requirements
+// Sends SIGTERM, waits 5s, then SIGKILL if still running
+await proc.terminate();
+```
 
-- **Node.js**: >= 16.x
-- **TypeScript**: >= 3.x (automatically handled by tsx)
+## API Quick Reference
+
+| Function | Execution | Returns | Best For |
+|----------|-----------|---------|----------|
+| `runPath()` | In-process (or child with `cwd`) | `Promise<void>` | Simple script execution, sequential workflows |
+| `runCli()` | In-process (or child with `cwd`) | `Promise<void>` | CLI-like invocation with argv integration |
+| `spawnPath()` | Always child process | `ITsrunChildProcess` | Output capture, timeouts, cancellation, parallel tasks |
+
+**Decision guide:**
+- 🎯 **Just run a script?** → `runPath()`
+- 🔧 **Need argv pass-through?** → `runCli()`
+- 🎛️ **Need stdout/stderr, timeout, or cancel?** → `spawnPath()`
+- ⚡ **Parallel execution across projects?** → `runPath()` with `cwd` or `spawnPath()`
+
+### `ITsrunChildProcess` Interface
+
+The object returned by `spawnPath()`:
+
+| Property / Method | Type | Description |
+|---|---|---|
+| `childProcess` | `ChildProcess` | Direct access to Node's ChildProcess |
+| `stdout` | `Readable \| null` | Stdout stream (`null` if stdio is `'inherit'`) |
+| `stderr` | `Readable \| null` | Stderr stream (`null` if stdio is `'inherit'`) |
+| `exitCode` | `Promise<number>` | Resolves with exit code when process ends |
+| `kill(signal?)` | `(signal?: NodeJS.Signals) => boolean` | Send a signal to the process |
+| `terminate()` | `() => Promise<void>` | Graceful shutdown: SIGTERM → 5s → SIGKILL |
+
+### `ISpawnOptions`
+
+Options for `spawnPath()`:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `cwd` | `string` | `process.cwd()` | Working directory for the child process |
+| `env` | `Record<string, string>` | `{}` | Extra env vars (merged with `process.env`) |
+| `args` | `string[]` | `[]` | Additional CLI arguments |
+| `stdio` | `'pipe' \| 'inherit'` | `'pipe'` | Stdio configuration |
+| `timeout` | `number` | — | Auto-kill after N milliseconds |
+| `signal` | `AbortSignal` | — | External cancellation support |
+
+## Features
+
+✨ **Zero Configuration** — Point and shoot. No tsconfig required, no build step, no setup.
+
+⚡ **Lightning Fast** — Powered by tsx (esbuild under the hood) for near-instant TypeScript execution.
+
+🔄 **Transparent Arguments** — CLI args pass through seamlessly to your scripts via `process.argv`.
+
+📦 **Dual Interface** — Use as a CLI tool or import as a library with full TypeScript types.
+
+🔀 **Custom Working Directory** — Run scripts in isolated child processes with different cwds.
+
+🎛️ **Full Process Control** — `spawnPath()` gives you streams, timeouts, cancellation, and graceful shutdown.
+
+🛡️ **Signal Forwarding** — SIGINT/SIGTERM/SIGHUP are properly forwarded to child processes.
+
+## Common Use Cases
+
+### Quick Scripts & Prototyping
+
+```bash
+# Write TypeScript, run it immediately
+tsrun seed-database.ts
+tsrun generate-report.ts --format csv
+tsrun cleanup-temp-files.ts
+```
+
+### Sequential Build Pipeline
+
+```typescript
+import { runPath } from '@git.zone/tsrun';
+
+const steps = ['./lint.ts', './test.ts', './build.ts', './deploy.ts'];
+
+for (const step of steps) {
+  console.log(`▶ Running ${step}...`);
+  await runPath(step, import.meta.url);
+  console.log(`✓ Done`);
+}
+```
+
+### Parallel Multi-Project Builds
+
+```typescript
+import { runPath } from '@git.zone/tsrun';
+
+await Promise.all([
+  runPath('./build.ts', undefined, { cwd: '/workspace/frontend' }),
+  runPath('./build.ts', undefined, { cwd: '/workspace/backend' }),
+  runPath('./build.ts', undefined, { cwd: '/workspace/shared' }),
+]);
+```
+
+### Long-Running Tasks with Monitoring
+
+```typescript
+import { spawnPath } from '@git.zone/tsrun';
+
+const proc = spawnPath('./data-migration.ts', import.meta.url, {
+  timeout: 300000,  // 5 minute max
+  env: { LOG_LEVEL: 'verbose' },
+});
+
+let lines = 0;
+proc.stdout?.on('data', (chunk) => {
+  lines++;
+  if (lines % 100 === 0) console.log(`Processed ${lines} lines...`);
+});
+
+try {
+  await proc.exitCode;
+  console.log('Migration completed!');
+} catch (err) {
+  console.error('Migration failed:', err.message);
+  process.exit(1);
+}
+```
+
+## Troubleshooting
+
+### "Cannot find module" errors
+
+Use `import.meta.url` for path resolution relative to the calling file:
+
+```typescript
+// ❌ Relative to cwd — fragile
+await runPath('./script.ts');
+
+// ✅ Relative to current file — reliable
+await runPath('./script.ts', import.meta.url);
+```
+
+### Process hangs
+
+When using `spawnPath()`, always await the `exitCode` promise:
+
+```typescript
+const proc = spawnPath('./script.ts', import.meta.url);
+await proc.exitCode; // Don't forget this!
+```
+
+### Timeout only works with `spawnPath()`
+
+`runPath()` executes in-process and doesn't support timeouts. Use `spawnPath()` instead:
+
+```typescript
+const proc = spawnPath('./script.ts', import.meta.url, { timeout: 5000 });
+await proc.exitCode;
+```
+
+### `tsrun: command not found`
+
+Install globally or use `npx`:
+
+```bash
+pnpm install -g @git.zone/tsrun
+# or
+npx @git.zone/tsrun myScript.ts
+```
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./license) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
 Task Venture Capital GmbH
-Registered at District court Bremen HRB 35230 HB, Germany
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tsrun',
-  version: '1.3.4',
+  version: '2.0.2',
   description: 'run typescript programs efficiently'
 }

ts/index.ts

@@ -1,14 +1,82 @@
 import * as plugins from './plugins.js';
 const __dirname = plugins.path.dirname(plugins.url.fileURLToPath(import.meta.url));
 
-export const runPath = async (pathArg: string, fromFileUrl?: string) => {
+export interface IRunOptions {
+  cwd?: string;
+}
+
+export interface ISpawnOptions {
+  /** Working directory for the child process */
+  cwd?: string;
+
+  /** Environment variables (merged with parent's env) */
+  env?: Record<string, string>;
+
+  /** Additional CLI arguments to pass to the script */
+  args?: string[];
+
+  /**
+   * Stdio configuration
+   * - 'pipe': Create pipes for stdin/stdout/stderr (default)
+   * - 'inherit': Use parent's stdio
+   * - Array: Custom configuration per stream
+   */
+  stdio?: 'pipe' | 'inherit' | ['pipe' | 'inherit' | 'ignore', 'pipe' | 'inherit' | 'ignore', 'pipe' | 'inherit' | 'ignore'];
+
+  /**
+   * Optional timeout in milliseconds
+   * If provided, process is automatically killed after timeout
+   */
+  timeout?: number;
+
+  /**
+   * AbortSignal for cancellation support
+   * Allows external cancellation of the process
+   */
+  signal?: AbortSignal;
+}
+
+export interface ITsrunChildProcess {
+  /** Direct access to Node's ChildProcess object */
+  childProcess: plugins.ChildProcess;
+
+  /** Readable stream for stdout (null if stdio is 'inherit') */
+  stdout: plugins.Readable | null;
+
+  /** Readable stream for stderr (null if stdio is 'inherit') */
+  stderr: plugins.Readable | null;
+
+  /** Promise that resolves with the exit code when process ends */
+  exitCode: Promise<number>;
+
+  /**
+   * Send signal to process
+   * Returns true if signal was sent successfully
+   */
+  kill(signal?: NodeJS.Signals): boolean;
+
+  /**
+   * Gracefully terminate the process
+   * Tries SIGTERM first, waits 5s, then SIGKILL if still running
+   * Returns a promise that resolves when process is terminated
+   */
+  terminate(): Promise<void>;
+}
+
+export const runPath = async (pathArg: string, fromFileUrl?: string, options?: IRunOptions) => {
   pathArg = fromFileUrl
     ? plugins.path.join(plugins.path.dirname(plugins.url.fileURLToPath(fromFileUrl)), pathArg)
     : pathArg;
-  await runCli(pathArg);
+  await runCli(pathArg, options);
 };
 
-export const runCli = async (pathArg?: string) => {
+export const runCli = async (pathArg?: string, options?: IRunOptions) => {
+  // CRITICAL: Branch BEFORE splicing argv to avoid corruption
+  if (options?.cwd) {
+    return runInChildProcess(pathArg, options.cwd);
+  }
+
+  // Existing in-process execution
   // contents of argv array
   // process.argv[0] -> node Executable
   // process.argv[1] -> tsrun executable
@@ -26,3 +94,182 @@ export const runCli = async (pathArg?: string) => {
   const unregister = tsx.register();
   await import(absolutePathToTsFile);
 };
+
+const runInChildProcess = async (pathArg: string | undefined, cwd: string): Promise<void> => {
+  const { spawn } = await import('child_process');
+
+  // Resolve cli.js relative to this file
+  const cliPath = plugins.path.join(__dirname, '../cli.js');
+
+  // Build args: [Node flags, entry point, script path, script args]
+  const args = [
+    ...process.execArgv,           // Preserve --inspect, etc.
+    cliPath,
+    ...process.argv.slice(2)       // Original CLI args (not spliced)
+  ];
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, args, {
+      cwd: cwd,
+      env: process.env,
+      stdio: 'inherit',
+      shell: false,
+      windowsHide: false
+    });
+
+    // Signal forwarding with cleanup
+    const signalHandler = (signal: NodeJS.Signals) => {
+      try { child.kill(signal); } catch {}
+    };
+
+    const signals: NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    signals.forEach(sig => process.on(sig, signalHandler));
+
+    child.on('error', (err) => {
+      signals.forEach(sig => process.off(sig, signalHandler));
+      reject(err);
+    });
+
+    child.on('close', (code, signal) => {
+      // Clean up signal handlers
+      signals.forEach(sig => process.off(sig, signalHandler));
+
+      if (signal) {
+        // Child was terminated by signal
+        // On POSIX: try to exit with same signal
+        // On Windows: exit with convention (128 + signal number)
+        try {
+          process.kill(process.pid, signal);
+        } catch {
+          // Fallback to exit code
+          const signalExitCode = signal === 'SIGINT' ? 130 : 128;
+          process.exit(signalExitCode);
+        }
+      } else if (code !== null && code !== 0) {
+        process.exit(code);
+      } else {
+        resolve();
+      }
+    });
+  });
+};
+
+export const spawnPath = (
+  filePath: string,
+  fromFileUrl?: string | URL,
+  options?: ISpawnOptions
+): ITsrunChildProcess => {
+  // 1. Resolve path (similar to runPath)
+  const resolvedPath = fromFileUrl
+    ? plugins.path.join(
+        plugins.path.dirname(
+          plugins.url.fileURLToPath(
+            typeof fromFileUrl === 'string' ? fromFileUrl : fromFileUrl.href
+          )
+        ),
+        filePath
+      )
+    : filePath;
+
+  // 2. Build spawn args
+  const cliPath = plugins.path.join(__dirname, '../cli.js');
+  const args = [
+    ...process.execArgv,
+    cliPath,
+    resolvedPath,
+    ...(options?.args || [])
+  ];
+
+  // 3. Build spawn options
+  const spawnOptions = {
+    cwd: options?.cwd || process.cwd(),
+    env: { ...process.env, ...options?.env },
+    stdio: options?.stdio || 'pipe',
+    shell: false,
+    windowsHide: false
+  };
+
+  // 4. Spawn child process
+  const child = plugins.spawn(process.execPath, args, spawnOptions);
+
+  // 5. Set up timeout if provided
+  let timeoutId: NodeJS.Timeout | undefined;
+  let timeoutTriggered = false;
+
+  if (options?.timeout) {
+    timeoutId = setTimeout(() => {
+      timeoutTriggered = true;
+      child.kill('SIGTERM');
+    }, options.timeout);
+  }
+
+  // 6. Set up AbortSignal if provided
+  let abortHandler: (() => void) | undefined;
+  if (options?.signal) {
+    abortHandler = () => {
+      child.kill('SIGTERM');
+    };
+    options.signal.addEventListener('abort', abortHandler);
+  }
+
+  // 7. Create exitCode promise
+  const exitCodePromise = new Promise<number>((resolve, reject) => {
+    child.on('close', (code: number | null, signal: NodeJS.Signals | null) => {
+      if (timeoutId) clearTimeout(timeoutId);
+      if (abortHandler && options?.signal) {
+        options.signal.removeEventListener('abort', abortHandler);
+      }
+
+      if (timeoutTriggered) {
+        reject(new Error(`Process killed: timeout of ${options?.timeout}ms exceeded`));
+      } else if (options?.signal?.aborted) {
+        reject(new Error('Process killed: aborted by signal'));
+      } else if (signal) {
+        reject(new Error(`Process killed with signal ${signal}`));
+      } else {
+        resolve(code || 0);
+      }
+    });
+
+    child.on('error', (err: Error) => {
+      if (timeoutId) clearTimeout(timeoutId);
+      if (abortHandler && options?.signal) {
+        options.signal.removeEventListener('abort', abortHandler);
+      }
+      reject(err);
+    });
+  });
+
+  // 8. Implement terminate() method
+  const terminate = async (): Promise<void> => {
+    return new Promise((resolve) => {
+      if (child.killed) {
+        resolve();
+        return;
+      }
+
+      child.kill('SIGTERM');
+
+      const killTimeout = setTimeout(() => {
+        if (!child.killed) {
+          child.kill('SIGKILL');
+        }
+      }, 5000);
+
+      child.on('close', () => {
+        clearTimeout(killTimeout);
+        resolve();
+      });
+    });
+  };
+
+  // 9. Return ITsrunChildProcess object
+  return {
+    childProcess: child,
+    stdout: child.stdout,
+    stderr: child.stderr,
+    exitCode: exitCodePromise,
+    kill: (signal?: NodeJS.Signals) => child.kill(signal),
+    terminate
+  };
+};

ts/plugins.ts

@@ -1,8 +1,12 @@
 // node native
 import * as path from 'path';
 import * as url from 'url';
+import { spawn } from 'child_process';
+import type { ChildProcess } from 'child_process';
+import type { Readable } from 'stream';
 
-export { path, url };
+export { path, url, spawn };
+export type { ChildProcess, Readable };
 
 // @pushrocks scope
 import * as smartfile from '@push.rocks/smartfile';

tsconfig.json

@@ -1,7 +1,5 @@
 {
   "compilerOptions": {
-    "experimentalDecorators": true,
-    "useDefineForClassFields": false,
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",