v2.0.2

.serena/.gitignore

@@ -0,0 +1 @@
+/cache

.serena/project.yml

@@ -0,0 +1,67 @@
+# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
+#  * For C, use cpp
+#  * For JavaScript, use typescript
+# Special requirements:
+#  * csharp: Requires the presence of a .sln file in the project folder.
+language: typescript
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "tsrun"

.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,77 @@
 # 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
+
+- Rewrite and expand README: clearer intro, installation, CLI and programmatic usage examples, features and examples, and updated package/project links.
+- Add packageManager entry to package.json to record pnpm version/hash (pnpm@10.18.1+sha512...).
+- Add pnpm-workspace.yaml with onlyBuiltDependencies for esbuild.
+- Add .serena/project.yml and .serena/.gitignore for project metadata and Serena tooling configuration.
+- Add .claude/settings.local.json to configure local agent permissions.
+- No functional TypeScript source changes in this commit (runtime implementations remain as placeholders).
+
+## 2024-10-27 - 1.3.3 - fix(core)
+removed unused import statement in ts/plugins.ts
+
+- Cleanup: Removed an unused import statement for tsImport from tsx/esm/api
+
 ## 2024-10-27 - 1.3.2 - fix(core)
 Replace ts-node with tsx for module handling
 

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.2",
+  "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": [
@@ -50,5 +49,6 @@
   "bugs": {
     "url": "https://gitlab.com/gitzone/tsrun/issues"
   },
-  "homepage": "https://gitlab.com/gitzone/tsrun#readme"
+  "homepage": "https://gitlab.com/gitzone/tsrun#readme",
+  "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
 }

readme.md

@@ -1,50 +1,345 @@
-# @gitzone/tsrun
+# @git.zone/tsrun
 
-run typescript programs efficiently
+[![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/)
 
-## Availabililty and Links
+> Run TypeScript files instantly — no build step, no config, no friction ⚡
 
-- [npmjs.org (npm package)](https://www.npmjs.com/package/@gitzone/tsrun)
-- [gitlab.com (source)](https://gitlab.com/gitzone/tsrun)
-- [github.com (source mirror)](https://github.com/gitzone/tsrun)
-- [docs (typedoc)](https://gitzone.gitlab.io/tsrun/)
+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.
 
-## Status for master
+## Issue Reporting and Security
 
-| Status Category                                 | Status Badge                                                                                                      |
-| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| GitLab Pipelines                                | [![pipeline status](https://gitlab.com/gitzone/tsrun/badges/master/pipeline.svg)](https://lossless.cloud)         |
-| GitLab Pipline Test Coverage                    | [![coverage report](https://gitlab.com/gitzone/tsrun/badges/master/coverage.svg)](https://lossless.cloud)         |
-| npm                                             | [![npm downloads per month](https://badgen.net/npm/dy/@gitzone/tsrun)](https://lossless.cloud)                    |
-| Snyk                                            | [![Known Vulnerabilities](https://badgen.net/snyk/gitzone/tsrun)](https://lossless.cloud)                         |
-| TypeScript Support                              | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud)        |
-| node Support                                    | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/) |
-| Code Style                                      | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud)                           |
-| PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@gitzone/tsrun)](https://lossless.cloud)               |
-| PackagePhobia (package size on registry)        | [![PackagePhobia](https://badgen.net/packagephobia/publish/@gitzone/tsrun)](https://lossless.cloud)               |
-| BundlePhobia (total size when bundled)          | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@gitzone/tsrun)](https://lossless.cloud)                  |
+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.
 
-## Usage
+## Table of Contents
 
-Use TypeScript for best in class instellisense.
+- [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)
 
-To simply run a TypeScript file on the fly type
+## What is tsrun?
 
-```typescript
-tsrun myfiletorun.ts
+**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
+
+**Global** (recommended for CLI usage):
+
+```bash
+pnpm install -g @git.zone/tsrun
 ```
 
-There are options available:
+**As a project dependency** (for programmatic API):
 
-- `--web` will inject browser types. this is useful when testing code with polyfills on node, but that is meant for the browser later on.
+```bash
+pnpm install @git.zone/tsrun
+```
 
-## Contribution
+## 🚀 CLI Usage
 
-We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)
+Run any TypeScript file:
 
-For further information read the linked docs at the top of this readme.
+```bash
+tsrun myScript.ts
+```
 
-## Legal
+Arguments pass through transparently, just like `node`:
 
-> MIT licensed | **©** [Task Venture Capital GmbH](https://task.vc)
-> | By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)
+```bash
+tsrun deploy.ts production --verbose --dry-run
+```
+
+Your script sees them in `process.argv` as expected:
+
+```typescript
+// deploy.ts
+const env = process.argv[0];     // "production"
+const verbose = process.argv.includes('--verbose');
+const dryRun = process.argv.includes('--dry-run');
+
+console.log(`Deploying to ${env}...`);
+```
+
+## 💻 Programmatic API
+
+tsrun exports three functions tailored for different execution needs.
+
+### `runPath()` — Simple Execution
+
+Runs a TypeScript file and waits for it to complete. The simplest way to execute scripts programmatically.
+
+```typescript
+import { runPath } from '@git.zone/tsrun';
+
+// Run a script (path relative to cwd)
+await runPath('./scripts/build.ts');
+
+// 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');
+}
+```
+
+**Graceful termination:**
+
+```typescript
+const proc = spawnPath('./server.ts', import.meta.url);
+
+// Sends SIGTERM, waits 5s, then SIGKILL if still running
+await proc.terminate();
+```
+
+## 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 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 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
+
+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.2',
+  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,15 +1,15 @@
 // 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';
 import * as smartshell from '@push.rocks/smartshell';
 
 export { smartfile, smartshell };
-
-import { tsImport } from 'tsx/esm/api';
-
-export { tsImport };

tsconfig.json

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