@tishlang/tish 1.7.0 → 1.8.0

package/Cargo.toml

@@ -28,6 +28,7 @@ members = [
     "crates/tish_fmt",
     "crates/tish_lint",
     "crates/tish_lsp",
+    "crates/tish_resolve",
     "crates/tishlang_cargo_bindgen",
 ]
 resolver = "2"

package/README.md

@@ -4,6 +4,8 @@
 
 This npm package ships the **Tish CLI**. It includes platform-specific native binaries under `platform/`; **`npm install`** runs `postinstall`, which copies the correct binary to `bin/tish`. That file is what runs when you invoke `tish` — the CLI itself is native, not Node. Node **22+** is required for install scripts and tooling (e.g. semantic-release in this repo); the `tish` binary has no Node runtime dependency.
 
+Those prebuilt binaries are built with **`--features full`** (http, fs, process, regex, ws) so `tish run` and the bytecode VM match a full developer toolchain. For a minimal CLI, build `tishlang` from the repo with `--no-default-features` (see the workspace `justfile`).
+
 ## Install
 
 ```bash

package/crates/js_to_tish/src/transform/expr.rs

@@ -89,9 +89,14 @@ pub fn convert_expr(expr: &OxcExpr<'_>, ctx: &Ctx<'_>) -> Result<Expr, ConvertEr
         }
         OxcExpr::StaticMemberExpression(s) => {
             let object = Box::new(convert_expr(&s.object, ctx)?);
+            let name = Arc::from(s.property.name.as_str());
+            let name_span = span_util::oxc_span_to_tish(ctx.1, &s.property);
             Ok(Expr::Member {
                 object,
-                prop: MemberProp::Name(Arc::from(s.property.name.as_str())),
+                prop: MemberProp::Name {
+                    name,
+                    span: name_span,
+                },
                 optional: s.optional,
                 span,
             })
@@ -241,9 +246,14 @@ fn convert_chain_element(
     match ce {
         oxc::ast::ast::ChainElement::StaticMemberExpression(m) => {
             let object = Box::new(convert_expr(&m.object, ctx)?);
+            let name = Arc::from(m.property.name.as_str());
+            let name_span = span_util::oxc_span_to_tish(ctx.1, &m.property);
             Ok(Expr::Member {
                 object,
-                prop: MemberProp::Name(Arc::from(m.property.name.as_str())),
+                prop: MemberProp::Name {
+                    name,
+                    span: name_span,
+                },
                 optional: m.optional,
                 span,
             })
@@ -504,8 +514,11 @@ pub fn convert_params(
     for (i, p) in params.items.iter().enumerate() {
         if params.rest.is_some() && i == params.items.len() - 1 {
             if let Some(rest) = &params.rest {
-                let rest_name = match &rest.rest.argument {
-                    oxc::ast::ast::BindingPattern::BindingIdentifier(b) => b.name.as_str(),
+                let (rest_name, rest_name_span) = match &rest.rest.argument {
+                    oxc::ast::ast::BindingPattern::BindingIdentifier(b) => (
+                        b.name.as_str(),
+                        crate::span_util::oxc_span_to_tish(ctx.1, b.as_ref()),
+                    ),
                     _ => {
                         return Err(ConvertError::new(ConvertErrorKind::Unsupported {
                             what: "rest param with non-identifier".into(),
@@ -515,6 +528,7 @@ pub fn convert_params(
                 };
                 rest_param = Some(TypedParam {
                     name: Arc::from(rest_name),
+                    name_span: rest_name_span,
                     type_ann: None,
                     default: None,
                 });
@@ -524,8 +538,10 @@ pub fn convert_params(
         // params.items contains FormalParameter structs (not enum)
         let fp = p;
         {
-            let name = match &fp.pattern {
-                oxc::ast::ast::BindingPattern::BindingIdentifier(b) => b.name.as_str(),
+            let (name, name_span) = match &fp.pattern {
+                oxc::ast::ast::BindingPattern::BindingIdentifier(b) => {
+                    (b.name.as_str(), crate::span_util::oxc_span_to_tish(ctx.1, b.as_ref()))
+                }
                 _ => {
                     return Err(ConvertError::new(ConvertErrorKind::Unsupported {
                         what: "destructuring in params".into(),
@@ -540,6 +556,7 @@ pub fn convert_params(
                 .transpose()?;
             typed_params.push(FunParam::Simple(TypedParam {
                 name: Arc::from(name),
+                name_span,
                 type_ann: None,
                 default,
             }));
@@ -547,8 +564,10 @@ pub fn convert_params(
     }
     if rest_param.is_none() {
         if let Some(rest) = &params.rest {
-            let rest_name = match &rest.rest.argument {
-                oxc::ast::ast::BindingPattern::BindingIdentifier(b) => b.name.as_str(),
+            let (rest_name, rest_name_span) = match &rest.rest.argument {
+                oxc::ast::ast::BindingPattern::BindingIdentifier(b) => {
+                    (b.name.as_str(), crate::span_util::oxc_span_to_tish(ctx.1, b.as_ref()))
+                }
                 _ => {
                     return Err(ConvertError::new(ConvertErrorKind::Unsupported {
                         what: "rest param with non-identifier".into(),
@@ -558,6 +577,7 @@ pub fn convert_params(
             };
             rest_param = Some(TypedParam {
                 name: Arc::from(rest_name),
+                name_span: rest_name_span,
                 type_ann: None,
                 default: None,
             });

package/crates/js_to_tish/src/transform/stmt.rs

@@ -149,8 +149,10 @@ fn convert_var_decl(
         match id {
             oxc::ast::ast::BindingPattern::BindingIdentifier(b) => {
                 let name: Arc<str> = Arc::from(b.name.as_str());
+                let name_span = span_util::oxc_span_to_tish(ctx.1, b.as_ref());
                 Ok(Statement::VarDecl {
                     name,
+                    name_span,
                     mutable,
                     type_ann: None,
                     init,
@@ -240,12 +242,14 @@ fn convert_for_of_statement(
     ctx: &Ctx<'_>,
     span: Span,
 ) -> Result<Statement, ConvertError> {
-    let name = match &f.left {
+    let (name, name_span) = match &f.left {
         oxc::ast::ast::ForStatementLeft::VariableDeclaration(v) => {
             if v.declarations.len() == 1 {
                 let d = &v.declarations[0];
                 match &d.id {
-                    oxc::ast::ast::BindingPattern::BindingIdentifier(b) => b.name.as_str(),
+                    oxc::ast::ast::BindingPattern::BindingIdentifier(b) => {
+                        (b.name.as_str(), span_util::oxc_span_to_tish(ctx.1, b.as_ref()))
+                    }
                     _ => {
                         return Err(ConvertError::new(ConvertErrorKind::Incompatible {
                             what: "for-of with destructuring".into(),
@@ -271,6 +275,7 @@ fn convert_for_of_statement(
     let body = Box::new(convert_statement(&f.body, ctx)?);
     Ok(Statement::ForOf {
         name: Arc::from(name),
+        name_span,
         iterable,
         body,
         span,
@@ -311,26 +316,30 @@ fn convert_try_statement(
         statements: body_stmts,
         span: span_util::oxc_span_to_tish(ctx.1, &*t.block),
     });
-    let (catch_param, catch_body) = match &t.handler {
+    let (catch_param, catch_param_span, catch_body) = match &t.handler {
         Some(h) => {
-            let param = h
+            let (param, pspan) = h
                 .param
                 .as_ref()
                 .and_then(|cp: &oxc::ast::ast::CatchParameter<'_>| {
                     if let oxc::ast::ast::BindingPattern::BindingIdentifier(b) = &cp.pattern {
-                        Some(Arc::from(b.name.as_str()))
+                        Some((
+                            Arc::from(b.name.as_str()),
+                            span_util::oxc_span_to_tish(ctx.1, b.as_ref()),
+                        ))
                     } else {
                         None
                     }
-                });
+                })
+                .map_or((None, None), |(n, s)| (Some(n), Some(s)));
             let catch_stmts = convert_statements(&h.body.body, ctx.0, ctx.1)?;
             let cb = Box::new(Statement::Block {
                 statements: catch_stmts,
                 span: span_util::oxc_span_to_tish(ctx.1, &*h.body),
             });
-            (param, Some(cb))
+            (param, pspan, Some(cb))
         }
-        None => (None, None),
+        None => (None, None, None),
     };
     let finally_body = t
         .finalizer
@@ -346,6 +355,7 @@ fn convert_try_statement(
     Ok(Statement::Try {
         body,
         catch_param,
+        catch_param_span,
         catch_body,
         finally_body,
         span,
@@ -358,10 +368,16 @@ fn convert_function_decl(
     span: Span,
 ) -> Result<Statement, ConvertError> {
     let async_ = f.r#async;
-    let name: Arc<str> =
-        f.id.as_ref()
-            .map(|id| Arc::from(id.name.as_str()))
-            .unwrap_or_else(|| Arc::from(""));
+    let name: Arc<str> = f
+        .id
+        .as_ref()
+        .map(|id| Arc::from(id.name.as_str()))
+        .unwrap_or_else(|| Arc::from(""));
+    let name_span = f
+        .id
+        .as_ref()
+        .map(|id| span_util::oxc_span_to_tish(ctx.1, id))
+        .unwrap_or_else(span_util::stub_span);
     let (params, rest_param) = expr::convert_params(&f.params, ctx)?;
     let body = match &f.body {
         Some(fb) => {
@@ -381,6 +397,7 @@ fn convert_function_decl(
     Ok(Statement::FunDecl {
         async_,
         name,
+        name_span,
         params,
         rest_param,
         return_type: None,
@@ -391,7 +408,7 @@ fn convert_function_decl(
 
 fn convert_import(
     i: &oxc::ast::ast::ImportDeclaration<'_>,
-    _ctx: &Ctx<'_>,
+    ctx: &Ctx<'_>,
     span: Span,
 ) -> Result<Statement, ConvertError> {
     let from: Arc<str> = Arc::from(i.source.value.as_str());
@@ -402,25 +419,35 @@ fn convert_import(
                 oxc::ast::ast::ImportDeclarationSpecifier::ImportSpecifier(is) => {
                     let imported_name = is.imported.name().as_str();
                     let local_name = is.local.name.as_str();
-                    let alias = if imported_name == local_name {
-                        None
+                    let name_span = crate::span_util::oxc_span_to_tish(ctx.1, &is.imported);
+                    let (alias, alias_span) = if imported_name == local_name {
+                        (None, None)
                     } else {
-                        Some(Arc::from(local_name))
+                        (
+                            Some(Arc::from(local_name)),
+                            Some(crate::span_util::oxc_span_to_tish(ctx.1, &is.local)),
+                        )
                     };
                     specifiers.push(tishlang_ast::ImportSpecifier::Named {
                         name: Arc::from(imported_name),
+                        name_span,
                         alias,
+                        alias_span,
                     });
                 }
                 oxc::ast::ast::ImportDeclarationSpecifier::ImportDefaultSpecifier(ds) => {
-                    specifiers.push(tishlang_ast::ImportSpecifier::Default(Arc::from(
-                        ds.local.name.as_str(),
-                    )));
+                    let name_span = crate::span_util::oxc_span_to_tish(ctx.1, &ds.local);
+                    specifiers.push(tishlang_ast::ImportSpecifier::Default {
+                        name: Arc::from(ds.local.name.as_str()),
+                        name_span,
+                    });
                 }
                 oxc::ast::ast::ImportDeclarationSpecifier::ImportNamespaceSpecifier(ns) => {
-                    specifiers.push(tishlang_ast::ImportSpecifier::Namespace(Arc::from(
-                        ns.local.name.as_str(),
-                    )));
+                    let name_span = crate::span_util::oxc_span_to_tish(ctx.1, &ns.local);
+                    specifiers.push(tishlang_ast::ImportSpecifier::Namespace {
+                        name: Arc::from(ns.local.name.as_str()),
+                        name_span,
+                    });
                 }
             }
         }

package/crates/tish/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tishlang"
-version = "1.7.0"
+version = "1.8.0"
 edition = "2021"
 description = "Tish CLI - run, REPL, compile to native"
 license-file = { workspace = true }
@@ -11,12 +11,21 @@ name = "tish"
 path = "src/main.rs"
 
 [features]
-# Default: secure mode with no dangerous capabilities
-default = []
-# Full: all capabilities enabled (for development/trusted environments)
-full = ["http", "fs", "process", "regex", "ws"]
+# The published `tish` CLI always includes every optional runtime (http, timers, fs, process, regex, ws).
+# Use `cargo build -p tishlang --no-default-features` when you need a locked-down toolchain
+# (see workspace `justfile`). `tish run --feature …` / `tish build --feature …` gate what runs
+# or what gets linked into a *native output* binary — they are not the primary way to ship a
+# “full” vs “empty” CLI.
+default = ["full"]
+# Alias: same dependency edges as `default` (kept for `--features full` in CI and docs).
+# Includes `pg` so `tish run` can resolve `import … from 'tish-pg'` (`cargo:tish_pg`) on the bytecode VM.
+# Requires `tish-pg` next to this workspace root (`…/tish/tish-pg`); CI runs `scripts/ci/ensure-tish-pg.sh`.
+full = ["http", "fs", "process", "regex", "ws", "timers", "pg"]
+# Opt-out: build without Postgres (`cargo build -p tishlang --no-default-features --features http,...`).
+pg = ["dep:tish_pg"]
 # Individual capability flags
 http    = ["tishlang_eval/http",    "tishlang_runtime/http",    "tishlang_compile/http",    "tishlang_vm/http"]
+timers  = ["tishlang_eval/timers",  "tishlang_compile/timers",  "tishlang_vm/timers"]
 fs      = ["tishlang_eval/fs",      "tishlang_runtime/fs",      "tishlang_compile/fs",      "tishlang_vm/fs"]
 process = ["tishlang_eval/process", "tishlang_runtime/process", "tishlang_compile/process", "tishlang_vm/process"]
 regex   = ["tishlang_eval/regex",   "tishlang_runtime/regex",   "tishlang_compile/regex",   "tishlang_vm/regex"]
@@ -40,6 +49,7 @@ tishlang_runtime = { path = "../tish_runtime", version = ">=0.1" }
 tishlang_core = { path = "../tish_core", version = ">=0.1" }
 tishlang_js_to_tish = { path = "../js_to_tish", version = ">=0.1" }
 clap = { version = "4.6.0", features = ["derive", "color"] }
+tish_pg = { path = "../../../tish-pg", package = "tish-pg", optional = true }
 
 [dev-dependencies]
 rayon = "1.11"

package/crates/tish/src/cargo_native_registry.rs

@@ -0,0 +1,29 @@
+//! Registers `cargo:*` Rust shims on the bytecode VM (`tish run`, REPL).
+//!
+//! Native `tish build` outputs register their own crates at link time; the
+//! interpreter path must populate [`tishlang_vm::Vm::register_native_module`].
+
+#[cfg(feature = "pg")]
+pub(crate) fn register_bytecode_native_modules(vm: &mut tishlang_vm::Vm) {
+    use std::sync::Arc;
+    use tishlang_core::{ObjectMap, Value};
+
+    let mut om = ObjectMap::with_capacity(8);
+    om.insert(
+        Arc::from("per_worker_client"),
+        Value::native(tish_pg::per_worker_client),
+    );
+    om.insert(Arc::from("connect"), Value::native(tish_pg::connect));
+    om.insert(Arc::from("prepare"), Value::native(tish_pg::prepare));
+    om.insert(
+        Arc::from("query_prepared"),
+        Value::native(tish_pg::query_prepared),
+    );
+    om.insert(Arc::from("query_all"), Value::native(tish_pg::query_all));
+    om.insert(Arc::from("migrate"), Value::native(tish_pg::migrate));
+    om.insert(Arc::from("close"), Value::native(tish_pg::close));
+    vm.register_native_module("cargo:tish_pg", om);
+}
+
+#[cfg(not(feature = "pg"))]
+pub(crate) fn register_bytecode_native_modules(_vm: &mut tishlang_vm::Vm) {}

package/crates/tish/src/cli_help.rs

@@ -337,7 +337,9 @@ fn capabilities_section(oh: &str, t: &str, r: &str) -> String {
 
 {oh}Capabilities{r} (--feature, repeatable; comma-separated values are split):
   {t}http{r}
-          Network: fetch, serve, Promise / timers (native async)
+          Network: fetch, fetchAll, serve, Promise (and `await`); enabling http also enables timers
+  {t}timers{r}
+          setTimeout, setInterval, clearTimeout, clearInterval (global + `import from \"timers\"` / tish:timers)
   {t}fs{r}
           Filesystem: readFile, writeFile, fileExists, isDir, readDir, mkdir
   {t}process{r}
@@ -347,9 +349,9 @@ fn capabilities_section(oh: &str, t: &str, r: &str) -> String {
   {t}ws{r}
           WebSocket client / server
   {t}full{r}
-          All of the above (http, fs, process, regex, ws)
+          All of the above (http, timers, fs, process, regex, ws)
 
-Omit --feature to use every capability linked into this binary."
+Omit --feature to allow every capability compiled into this `tish` binary; pass flags to restrict what scripts may use. The CLI is normally built with all of them (Cargo default on `tishlang`)."
     )
 }
 
@@ -414,7 +416,9 @@ pub fn build_after_help() -> String {
 
 {oh}Capabilities{r} (--feature, repeatable; comma-separated values are split):
   {t}http{r}
-          Network: fetch, serve, Promise / timers (native async)
+          Network: fetch, fetchAll, serve, Promise (and `await`); enabling http also enables timers
+  {t}timers{r}
+          setTimeout, setInterval, clearTimeout, clearInterval (global + `import from \"timers\"` / tish:timers)
   {t}fs{r}
           Filesystem: readFile, writeFile, fileExists, isDir, readDir, mkdir
   {t}process{r}
@@ -424,10 +428,9 @@ pub fn build_after_help() -> String {
   {t}ws{r}
           WebSocket client / server
   {t}full{r}
-          All of the above (http, fs, process, regex, ws)
+          All of the above (http, timers, fs, process, regex, ws)
 
-Omit --feature to use every capability linked into this binary.
-Build `tish` with matching Cargo features (e.g. cargo build -p tishlang --features full)."
+For `--target native`, these choose what is linked into the **output** executable (omit = same set as this `tish` binary was built with). Minimal native outputs still use a full `tish` CLI unless you built it with `cargo build -p tishlang --no-default-features`."
     )
 }
 
@@ -458,7 +461,7 @@ pub(crate) struct RunArgs {
         help_heading = "Options"
     )]
     pub backend: String,
-    /// Subset of capabilities (see `tish --help` for the full list).
+    /// Restrict which platform APIs the script may use (omit = all capabilities compiled into this `tish`).
     #[arg(
         long = "feature",
         value_name = "NAME",
@@ -481,7 +484,7 @@ pub(crate) struct ReplArgs {
         help_heading = "Options"
     )]
     pub backend: String,
-    /// Subset of capabilities (see `tish --help` for the full list).
+    /// Restrict which platform APIs the REPL may use (omit = all capabilities compiled into this `tish`).
     #[arg(
         long = "feature",
         value_name = "NAME",
@@ -519,7 +522,7 @@ pub(crate) struct BuildArgs {
         help_heading = "Options"
     )]
     pub native_backend: String,
-    /// Capability subset for native output (see long help below).
+    /// For `--target native`: which capabilities to link into the produced binary (omit = same as this `tish`; see long help).
     #[arg(
         long = "feature",
         value_name = "NAME",
@@ -529,6 +532,9 @@ pub(crate) struct BuildArgs {
     pub features: Vec<String>,
     #[arg(long, help_heading = "Options")]
     pub no_optimize: bool,
+    /// For `--target js` project builds: emit `OUTPUT.js.map` and `//# sourceMappingURL=…` so JS/TS tools can jump to original `.tish` (implies `--no-optimize` for that build).
+    #[arg(long, help_heading = "Options")]
+    pub source_map: bool,
     /// Entry `.tish` file (or `.js` where supported).
     #[arg(required = true, value_name = "FILE", help_heading = "Arguments")]
     pub file: String,

package/crates/tish/src/main.rs

@@ -1,9 +1,11 @@
 //! Tish CLI - run, REPL, build to native or other targets.
 
+mod cargo_native_registry;
 mod cli_help;
 mod repl_completion;
 
 use std::cell::RefCell;
+use tishlang_core::VmRef;
 use std::collections::HashSet;
 use std::fs;
 use std::io::{self, IsTerminal, Read, Write};
@@ -15,13 +17,13 @@ use rustyline::{Behavior, ColorMode, CompletionType, Config, Editor};
 
 use cli_help::{Cli, Commands};
 
-/// Normalize `--feature` / `--feature http,fs` / `--feature full` for VM runs and native builds.
+/// Normalize `--feature` / `--feature http,timers,fs` / `--feature full` for VM runs and native builds.
 fn normalize_capability_flags(features: &[String]) -> HashSet<String> {
     let mut out = HashSet::new();
     for s in features {
         for part in s.split(',').map(str::trim).filter(|p| !p.is_empty()) {
             if part == "full" {
-                for name in ["http", "fs", "process", "regex", "ws"] {
+                for name in ["http", "timers", "fs", "process", "regex", "ws"] {
                     out.insert(name.to_string());
                 }
             } else {
@@ -110,6 +112,7 @@ fn main() {
             &a.native_backend,
             &a.features,
             a.no_optimize || no_opt_env,
+            a.source_map,
         ),
         Some(Commands::DumpAst { file }) => dump_ast(&file),
         None => {
@@ -160,7 +163,7 @@ fn run_stdin_source(
     let cwd = std::env::current_dir().map_err(|e| e.to_string())?;
     let modules = tishlang_compile::resolve_project_from_stdin(source, &cwd)?;
     tishlang_compile::detect_cycles(&modules)?;
-    let prog = tishlang_compile::merge_modules(modules)?;
+    let prog = tishlang_compile::merge_modules(modules)?.program;
     let program = if no_optimize {
         prog
     } else {
@@ -202,7 +205,7 @@ fn run_file(
         } else {
             let modules = tishlang_compile::resolve_project(&path, project_root)?;
             tishlang_compile::detect_cycles(&modules)?;
-            let prog = tishlang_compile::merge_modules(modules)?;
+            let prog = tishlang_compile::merge_modules(modules)?.program;
             if no_optimize {
                 prog
             } else {
@@ -223,6 +226,10 @@ fn run_program(
     if backend == "interp" {
         let mut eval = tishlang_eval::Evaluator::new();
         let value = eval.eval_program(program)?;
+        #[cfg(feature = "timers")]
+        {
+            let _ = eval.run_timer_phase();
+        }
         if !matches!(value, tishlang_eval::Value::Null) {
             println!(
                 "{}",
@@ -241,13 +248,9 @@ fn run_program(
         tishlang_bytecode::compile(program).map_err(|e| e.to_string())?
     };
     let caps = vm_capabilities_for_cli_run(features);
-    let value = tishlang_vm::run_with_options(
-        &chunk,
-        tishlang_vm::VmRunOptions {
-            repl_mode: false,
-            capabilities: caps,
-        },
-    )?;
+    let mut vm = tishlang_vm::Vm::with_capabilities(caps);
+    cargo_native_registry::register_bytecode_native_modules(&mut vm);
+    let value = vm.run_with_options(&chunk, false)?;
     if !matches!(value, tishlang_core::Value::Null) {
         println!(
             "{}",
@@ -294,6 +297,10 @@ fn run_repl(backend: &str, no_optimize: bool, features: &[String]) -> Result<(),
                 Ok(program) => {
                     match eval.eval_program(&program) {
                         Ok(v) => {
+                            #[cfg(feature = "timers")]
+                            {
+                                let _ = eval.run_timer_phase();
+                            }
                             if !matches!(v, tishlang_eval::Value::Null) {
                                 println!(
                                     "{}",
@@ -325,11 +332,11 @@ fn run_repl(backend: &str, no_optimize: bool, features: &[String]) -> Result<(),
     if !std::io::stdin().is_terminal() {
         eprintln!("Note: Tab completion and grey preview require an interactive terminal (TTY).");
     }
-    let vm = Rc::new(RefCell::new(tishlang_vm::Vm::with_capabilities(
-        vm_capabilities_for_cli_run(features),
-    )));
+    let mut vm0 = tishlang_vm::Vm::with_capabilities(vm_capabilities_for_cli_run(features));
+    cargo_native_registry::register_bytecode_native_modules(&mut vm0);
+    let vm = VmRef::new(vm0);
     let completer = repl_completion::ReplCompleter {
-        vm: Rc::clone(&vm),
+        vm: vm.clone(),
         no_optimize,
     };
     let config = Config::builder()
@@ -455,7 +462,27 @@ fn tish_history_path() -> Option<PathBuf> {
     home.map(|h| PathBuf::from(h).join(".tish_history"))
 }
 
-fn compile_to_js(input_path: &Path, output_path: &str, optimize: bool) -> Result<(), String> {
+fn compile_to_js(
+    input_path: &Path,
+    output_path: &str,
+    optimize: bool,
+    source_map: bool,
+) -> Result<(), String> {
+    if source_map && optimize {
+        return Err(
+            "tish build --target js --source-map requires --no-optimize (mappings follow unmerged statement order)."
+                .into(),
+        );
+    }
+    if source_map
+        && (input_path.extension().map(|e| e == "jsx") == Some(true)
+            || input_path.extension().map(|e| e == "js") == Some(true))
+    {
+        return Err(
+            "tish build --target js --source-map is only supported for .tish project builds (not single-file .jsx / .js inputs)."
+                .into(),
+        );
+    }
     let project_root = input_path.parent().and_then(|p| {
         if p.file_name().and_then(|n| n.to_str()) == Some("src") {
             p.parent()
@@ -463,7 +490,20 @@ fn compile_to_js(input_path: &Path, output_path: &str, optimize: bool) -> Result
             Some(p)
         }
     });
-    let js = if input_path.extension().map(|e| e == "jsx") == Some(true) {
+    let out_path = Path::new(output_path);
+    let out_path = if out_path.extension().is_none()
+        || out_path.extension() == Some(std::ffi::OsStr::new(""))
+    {
+        out_path.with_extension("js")
+    } else {
+        out_path.to_path_buf()
+    };
+    let out_js_name = out_path
+        .file_name()
+        .and_then(|s| s.to_str())
+        .unwrap_or("out.js");
+
+    let (js, map_json) = if input_path.extension().map(|e| e == "jsx") == Some(true) {
         let source = fs::read_to_string(input_path).map_err(|e| format!("{}", e))?;
         let wrapped = format!(
             "export fn __TishJsxRoot() {{\n  return (\n{}\n  )\n}}",
@@ -476,30 +516,44 @@ fn compile_to_js(input_path: &Path, output_path: &str, optimize: bool) -> Result
         } else {
             program
         };
-        tishlang_compile_js::compile_with_jsx(&p, optimize).map_err(|e| format!("{}", e))?
+        let js = tishlang_compile_js::compile_with_jsx(&p, optimize).map_err(|e| format!("{}", e))?;
+        (js, None)
     } else if input_path.extension().map(|e| e == "js") == Some(true) {
         let source = fs::read_to_string(input_path).map_err(|e| format!("{}", e))?;
         let program = tishlang_js_to_tish::convert(&source).map_err(|e| format!("{}", e))?;
-        tishlang_compile_js::compile_with_jsx(&program, optimize).map_err(|e| format!("{}", e))?
-    } else {
-        tishlang_compile_js::compile_project_with_jsx(input_path, project_root, optimize)
-            .map_err(|e| format!("{}", e))?
-    };
-
-    let out_path = Path::new(output_path);
-    let out_path = if out_path.extension().is_none()
-        || out_path.extension() == Some(std::ffi::OsStr::new(""))
-    {
-        out_path.with_extension("js")
+        let js =
+            tishlang_compile_js::compile_with_jsx(&program, optimize).map_err(|e| format!("{}", e))?;
+        (js, None)
+    } else if source_map {
+        let bundle = tishlang_compile_js::compile_project_with_jsx_and_source_map(
+            input_path,
+            project_root,
+            out_js_name,
+        )
+        .map_err(|e| format!("{}", e))?;
+        (bundle.js, bundle.source_map_json)
     } else {
-        out_path.to_path_buf()
+        let js = tishlang_compile_js::compile_project_with_jsx(input_path, project_root, optimize)
+            .map_err(|e| format!("{}", e))?;
+        (js, None)
     };
 
     if let Some(parent) = out_path.parent() {
         fs::create_dir_all(parent)
             .map_err(|e| format!("Cannot create output directory {}: {}", parent.display(), e))?;
     }
-    fs::write(&out_path, js).map_err(|e| format!("Cannot write {}: {}", out_path.display(), e))?;
+    let mut js_out = js;
+    if let Some(map) = &map_json {
+        let map_path = out_path.with_extension("js.map");
+        fs::write(&map_path, map).map_err(|e| format!("Cannot write {}: {}", map_path.display(), e))?;
+        let map_url = map_path
+            .file_name()
+            .and_then(|s| s.to_str())
+            .unwrap_or("out.js.map");
+        js_out.push_str(&format!("\n//# sourceMappingURL={map_url}\n"));
+        println!("Built: {}", map_path.display());
+    }
+    fs::write(&out_path, js_out).map_err(|e| format!("Cannot write {}: {}", out_path.display(), e))?;
     println!("Built: {}", out_path.display());
     Ok(())
 }
@@ -512,6 +566,7 @@ fn build_file(
     native_backend: &str,
     cli_features: &[String],
     no_optimize: bool,
+    source_map: bool,
 ) -> Result<(), String> {
     let optimize = !no_optimize;
     let input_path = Path::new(input_path)
@@ -521,7 +576,7 @@ fn build_file(
     let is_js = input_path.extension().map(|e| e == "js") == Some(true);
 
     if target == "js" {
-        return compile_to_js(&input_path, output_path, optimize);
+        return compile_to_js(&input_path, output_path, optimize, source_map);
     }
 
     if target == "wasm" && is_js {