TypedShell
tsh is an experimental language implemented in Rust that compiles a statically
checked subset of TypeScript syntax into readable, standalone shell scripts.
The crates.io package is named typedshell; its Rust library and installed CLI
are both named tsh.
The Bash backend generates scripts that execute with Bash 3.2 or newer, and the
PowerShell backend generates scripts for PowerShell 7.4 or newer (PowerShell 5.1
is out of scope). Generated scripts need no JavaScript runtime or installed
tsh executable.
Install
Build with Rust 1.97 or newer (required by Oxc 0.153):
# Or install from a local checkout:
# Or use cargo run -- <arguments> during development.
Usage
# PowerShell backend (requires `pwsh` 7.4+ to execute)
Both .tsh and .ts inputs use TypeScript parsing, independent of their extension.
The defaults are the Bash target, the compiler's host OS, all source comments,
and output beside the source with a .sh extension (.ps1 for --target pwsh).
The available targets are bash and pwsh; the available target OS values are
linux, macos, windows, and freebsd. Choosing an OS changes conditional
compilation and module compatibility. It does not install a shell or make
platform utilities available on another system. A single .tsh file compiles to
both .sh and .ps1:
Immediate execution compiles into memory and uses a private, automatically deleted
temporary script file, avoiding command-line length limits while leaving stdin
available to the program. It inherits the working directory, environment, and
standard streams, forwards each argument unchanged, and returns the script's exit
code. Bash output runs through bash; --target pwsh runs through
pwsh -NoProfile -File and reports a clear error when pwsh is not installed.
No permanent artifact is written in this mode. Generated source is never
executed through eval (or Invoke-Expression).
Language
class User {
constructor(public name: string) {}
rename(name: string): void {
this.name = name;
}
greet(): void {
echo(`Hello, ${this.name}!`);
}
}
const user = new User("Twilight");
user.greet();
user.rename("Arch");
user.greet();
The initial subset includes const and let, strings, integer numbers, booleans,
type annotations, templates, arithmetic and comparisons, assignments, typed
functions, if/else, while, and basic C-style for loops. Classes support
constructors, parameter properties, instance fields, mutable fields, instance
methods, static methods, and statically resolved method calls.
Class instances use integer identities and Bash indexed arrays for field storage. Functions and methods return through an explicit result slot. Calls execute in the current shell, so changes to objects and global variables survive returned values. Recursive calls preserve their local values.
The PowerShell backend instead uses native PowerShell classes with typed
properties, constructors, and instance/static methods, and compiles tsh
functions to PowerShell functions. Module-scope variables are accessed through
script scope inside functions and methods so mutations survive calls, while
parameters and locals stay function-local (preserving recursion). IR names are
already collision-free; because PowerShell identifiers are case-insensitive,
uniqueness holds through the generated numeric suffixes (for example,
__tsh_v_foo_0 versus __tsh_v_Foo_1). Function return values are captured
explicitly and discarded values are assigned to $null, so intermediate
pipeline output can never leak into a return value. Integer division uses
[Math]::DivRem to stay exact for 64-bit values and truncate toward zero,
matching the Bash backend. String comparisons use the case-sensitive -c*
operators; PowerShell's default case-insensitive operators are never used for
tsh values.
Numbers are signed shell integers, with integer division and Bash arithmetic
overflow semantics. String ordering follows the shell's locale. There is no
floating point, JavaScript coercion, or JavaScript
object model. Shell strings cannot represent NUL bytes. Shell command arguments
and interpolated values are quoted; ordinary strings are never evaluated as shell
code. raw!() deliberately bypasses those guarantees.
Unsupported syntax produces compiler diagnostics. Async/await, promises,
generators, inheritance, decorators, dynamic imports, arbitrary JavaScript APIs,
arrow functions, general arrays/objects, and npm/Node modules are outside this
subset. Array literals are accepted for run arguments and a literal options
object is accepted for mkdir/rm.
Intrinsics
Core shell operations are globally available:
| Operation | Behavior |
|---|---|
echo(value) |
Print one value followed by a newline |
mkdir(path, { recursive: true }) |
Create a directory, optionally including parents |
rm(path, { recursive: true }) |
Remove a path, optionally recursively |
cp(source, destination) |
Copy a file |
mv(source, destination) |
Move a path |
cd(path) |
Change the script's working directory |
run(command, [args...]) |
Execute a command with separately quoted arguments |
env(name) |
Read an environment variable; unset variables yield an empty string |
exit(code) |
Terminate the script, defaulting to zero |
Native command failures terminate the script with the actual failing exit code.
The backend checks command status explicitly instead of using set -e as language
semantics. Raw shell controls its own failure handling and can change shell state.
The generated script depends on any native commands explicitly used by the source.
The PowerShell backend maps intrinsics to native cmdlets and .NET APIs:
echo() to [Console]::WriteLine(), mkdir() to New-Item -Path
(-Force for recursive), rm() to Remove-Item -LiteralPath
(-Recurse -Force for recursive), cp()/mv() to Copy-Item/Move-Item -LiteralPath with -Force, cd() to Set-Location -LiteralPath (plus a
process-directory sync so child processes see the new directory),
run() to a System.Diagnostics.Process invocation with an exact .NET
ArgumentList (no wildcard expansion, boundaries preserved),
env() to [System.Environment]::GetEnvironmentVariable, and exit() to
exit. Every cmdlet failure exits 1; run() propagates the real exit code.
Literal paths are used throughout so wildcard characters are never expanded.
import { chmod } from "tsh:unix" provides chmod(path, 0o755) for Unix OS targets.
Built-in module compatibility is checked even for empty imports. Module names do
not imply a platform API is implemented; unavailable exports are rejected. On the
PowerShell target, numeric modes use [System.IO.File]::SetUnixFileMode; string
modes such as u+x are rejected with a diagnostic (use a numeric mode instead).
Known Bash/PowerShell differences: non-recursive rm of a directory fails on
both (PowerShell guards this explicitly); removing write-protected files succeeds
on PowerShell (-Force avoids interactive prompts) but fails on Bash; mv onto
itself succeeds on PowerShell; copying device files such as /dev/null works on
Bash but not through Copy-Item.
Conditional compilation
// @cfg(windows)
import {} from "tsh:windows";
// #if unix && shell("bash")
echo("Unix Bash target");
// #elif windows
echo("Windows target");
// #else
echo("Other target");
// #endif
Predicates include windows, linux, macos, freebsd, unix, and shell(...).
shell("bash") is true for --target bash; shell("pwsh") (or
shell("powershell")) is true for --target pwsh. Use !, &&, ||, and
parentheses to combine them. @cfg applies to the following statement. Block
directives nest. Inactive source is blanked before parsing and module
resolution, preserving byte positions for diagnostics; excluded imports are
never opened or validated. The compilation target and --os determine
predicate values and built-in module compatibility (for example,
tsh:windows is rejected unless the target OS is Windows, regardless of the
shell target). No runtime conditional branches are generated for
compile-time conditions.
Local modules
// utils.tsh
export function greeting(name: string): string {
return `Hello, ${name}!`;
}
// main.tsh
import { greeting } from "./utils.tsh";
echo(greeting("Bash"));
Local modules resolve relative to their importer and are bundled into the final standalone script. Cycles are rejected. Use named exports and imports with matching names; default imports, namespace imports, and aliases are outside the initial subset. Modules are not loaded at runtime.
Raw shell and comments
raw!(`
trap 'printf "%s\n" "Cleaning up"' EXIT
printf '%s\n' 'Native Bash works!'
`);
raw!() accepts only a string literal or a template with no substitutions. It
injects shell text at that statement's position, including inside functions and
methods. The compiler does not interpret, execute, or syntax-check raw contents.
Dynamic arguments and plain raw() calls are errors. Guard backend-specific raw
blocks with @cfg(shell("bash")) or @cfg(shell("pwsh")):
// @cfg(shell("pwsh"))
raw!(`
Write-Host 'Native PowerShell'
`);
--comments all preserves ordinary and documentation comments as shell comments
(# in both backends), including doc comments on functions, classes, and class
methods; doc keeps documentation comments; none omits source comments.
Compiler directives are omitted in every mode. Comments and text inside raw
blocks always remain unchanged.
Rust API and compiler structure
use ;
let script = compile_source?;
# Ok::
compile_file resolves local modules and emits shell source. check_file returns
the validated IR without executing it. Errors carry named source text and spans
for Miette rendering. Compiler state is owned by each compilation.
The pipeline is conditional preprocessing → Oxc TypeScript AST → module resolution
→ custom semantic validation → typed IR → backend code generation
(Bash or PowerShell, selected by --target). The backend consumes only the IR,
never Oxc nodes. The PowerShell emitter lives in src/backends/powershell/
(mod.rs, emitter.rs) behind the same backends::Backend trait. Parsing and
language semantics stay shared; platform-specific operations belong in module
metadata and target emission.
Embedding and custom backends
Add the package to your Cargo.toml; use tsh as the Rust crate name:
[]
= "0.1"
compile_source compiles source text, and compile_file resolves and bundles
local imports from a file. Both return generated shell source that your host
application can write, inspect, or execute with tsh::runner::run or
tsh::runner::run_pwsh.
Runnable examples are in embed_source.rs
and embed_file.rs.
To add an output format, implement tsh::backends::Backend and pass the
Program returned by check_file to it. The example
custom_backend.rs
implements a small JSON summary backend over the validated typed IR.
Publishing
The first release must be published locally. After creating and verifying a crates.io account, log in and run these commands from the repository root:
--allow-dirty is needed while these release-preparation changes are uncommitted;
omit it if you commit them locally first. Confirm that typedshell is still
available before publishing, since crate names are first-come, first-served.
After the first version is published and this workflow is on GitHub, follow the
crates.io Trusted Publishing setup and configure
crates.io Trusted Publishing for owner twlite, repository typedshell, and
workflow .github/workflows/publish.yml (leave the environment empty). Then
future releases can be started from Actions → Publish → Run workflow with a
version such as 0.2.0 or 0.2.0-rc.1, or by pushing to main a commit message
containing one unique matching version, such as release 0.2.0. The
workflow changes the manifest and lockfile in its temporary runner checkout to
publish the requested version; it does not create a version-bump commit.
Do not use a version token in the commit that first pushes this workflow after
publishing locally, or the push trigger will try to publish that same version
again. The workflow only publishes on main.
Development
Tests execute standalone generated scripts with Bash, including regressions for
subshell state loss, quoting, recursive returns, separate instance identity,
conditional imports, comments, CLI arguments, stdin, and exit status.
tests/powershell.rs mirrors that coverage for the PowerShell backend and
executes generated .ps1 scripts with pwsh when installed (compiler-only
assertions always run), plus cross-backend tests that compare Bash and
PowerShell output for equivalent programs.
This is an experimental compiler. The supported subset is intentionally smaller than TypeScript and raw shell is responsible for its own correctness. See the integration tests and examples for executable language contracts.