zsh/

lib.rs

//! Zsh interpreter and parser in Rust
//!
//! This crate provides:
//! - A complete zsh lexer (`lexer` module)
//! - A zsh parser (`parser` module)  
//! - Shell execution engine (`exec` module)
//! - Job control (`jobs` module)
//! - History management (`history` module)
//! - ZLE (Zsh Line Editor) support (`zle` module)
//! - ZWC (compiled zsh) support (`zwc` module)
//! - Fish-style features (`fish_features` module)
//! - Mathematical expression evaluation (`math` module)

// Many doc comments reference C-source pages, shell constructs, and
// zsh-internal identifiers by name in `[...]` form; they don't resolve as
// rustdoc intra-doc links. Silence so docs build clean on CI.
#![allow(rustdoc::broken_intra_doc_links)]
#![allow(rustdoc::private_intra_doc_links)]
#![allow(rustdoc::invalid_html_tags)]
#![allow(dead_code)]
#![allow(unused_variables)]
#![allow(unused_imports)]
#![allow(unused_assignments)]
#![allow(unused_mut)]
#![allow(unused_parens)]
#![allow(unused_doc_comments)]
#![allow(unreachable_patterns)]
#![allow(deprecated)]
#![allow(unexpected_cfgs)]
// Allow zsh-canonical identifier names (lowercase statics/constants/types
// like `ca_parsed`, `convchar_t`, `P_ISBRANCH`) so the ports stay
// faithful to the C source per PORT.md.
#![allow(non_snake_case)]
#![allow(non_camel_case_types)]
#![allow(non_upper_case_globals)]
// Function-pointer-to-integer casts appear in ported dispatch tables.
#![allow(function_casts_as_integer)]
// Clippy: the C → Rust ports preserve idioms from the zsh source
// (raw pointer derefs, dead-loop `do { ... } while (0)` shapes, bitmasks
// that look redundant but match the C, etc.). Silence the whole group so
// port fidelity wins over Rust-idiom rewrites. New non-ported code
// should still aim for clippy-clean, but at file/function scope, not
// crate-wide.
#![allow(clippy::all)]

/// Runtime shell-mode flag set by the binary entrypoint (`bins/zshrs.rs`)
/// at startup. The library can't directly read `bins/zshrs.rs::shell_mode()`
/// (it lives in the binary crate), so the binary writes this atomic when
/// parsing `--zsh` / `--bash` / `--posix` and the library reads it from
/// bridge / dispatch sites that need to gate bash-compat-vs-zsh behavior.
/// Defaults to `false` (zshrs-native mode) when not explicitly set.
///
/// Bugs #475 / #504 / #555 in docs/BUGS.md — bash-only builtins
/// (`caller`/`help`/`mapfile`/`readarray`/`compgen`/etc.) should
/// dispatch as "command not found" when this is true.
pub static IS_ZSH_MODE: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

/// `compsys` submodule.
pub mod compsys;
/// `exec_jobs` submodule.
pub mod exec_jobs;
/// `extensions` submodule.
pub mod extensions;
/// `metafied_key` submodule (Rust-only; see the module docs).
pub mod metafied_key;
/// `ported` submodule.
pub mod ported;
/// `pattern_data_escape` submodule (Rust-only; see the module docs).
pub mod pattern_data_escape;
/// `script_bytes` submodule (Rust-only; see the module docs).
pub mod script_bytes;
/// `token_char` submodule (Rust-only): where token chars live in a `char` string.
pub mod token_char;
/// `zlong_cast` submodule (Rust-only): C's `(zlong) double` with the host CPU's out-of-range answer.
pub mod zlong_cast;
/// `host_libc` submodule (Rust-only): host-libc behaviours C zsh inherits by calling libc.
pub mod host_libc;
/// `subscript_escape` submodule (Rust-only; see the module docs).
pub mod subscript_escape;
/// `test_util` submodule.
#[cfg(test)]
pub mod test_util;
/// `tiers` submodule.
pub mod tiers;
pub mod tolerant_sort;

// Back-compat: re-export every ported submodule at the crate root so
// historical call sites (`crate::exec::`, `crate::subst::`,
// `crate::zle::`, `crate::modules::`, `crate::builtins::`, etc.)
// continue to resolve unchanged after the physical move into
// `src/ported/`. New code should prefer `crate::ported::<name>`.
pub use ported::*;
/// `ai` submodule — the `ai` builtin's provider engine (config, cost
/// accounting, response cache, mock mode, SSE streaming). Ported from
/// `strykelang/strykelang/ai.rs`.
#[path = "extensions/ai.rs"]
pub mod ai;
/// `alias_input_frames` submodule — per-thread record of popped alias
/// input-stack frames, restoring the reachability C's manually-indexed
/// `instack` gives `input_hasalias`.
#[path = "extensions/alias_input_frames.rs"]
pub mod alias_input_frames;
/// `aot` submodule.
#[path = "extensions/aot.rs"]
pub mod aot;
/// `arith_compiler` submodule.
#[path = "extensions/arith_compiler.rs"]
pub mod arith_compiler;
/// `atexit_teardown` submodule — whether a libc `atexit` hook is running,
/// so the log sites they reach can skip TLS-backed `tracing`.
#[path = "extensions/atexit_teardown.rs"]
pub mod atexit_teardown;
/// `atomic_write` submodule — the shared temp-file-safe shard writer
/// used by both rkyv caches.
#[path = "extensions/atomic_write.rs"]
pub mod atomic_write;
/// `autoload_cache` submodule.
#[path = "extensions/autoload_cache.rs"]
pub mod autoload_cache;
/// `autoload_prewarm` submodule.
#[path = "extensions/autoload_prewarm.rs"]
pub mod autoload_prewarm;
/// `deparse_cache` submodule.
#[path = "extensions/deparse_cache.rs"]
pub mod deparse_cache;
/// `banner` submodule — the `zbanner` builtin and `zshrs --banner`
/// (logo, builtin totals, daemon and shell counts). Ported from ztmux.
#[path = "extensions/banner.rs"]
pub mod banner;
/// `bundled_docs` submodule — zsh's man/info pages, shipped in-binary.
#[path = "extensions/bundled_docs.rs"]
pub mod bundled_docs;
#[path = "extensions/bundled_functions.rs"]
pub mod bundled_functions;
/// `c_locale` submodule — `mbrtowc`/`wcrtomb` with one C-locale (ASCII)
/// answer on every platform; re-exported by `ported::utils`.
#[path = "extensions/c_locale.rs"]
pub mod c_locale;
/// `system_libm` submodule — the C library's `cbrt` for zsh/mathfunc (Rust's
/// compiler_builtins shadows it on Linux).
#[path = "extensions/system_libm.rs"]
pub mod system_libm;
/// `bash_complete` submodule.
#[path = "extensions/bash_complete.rs"]
pub mod bash_complete;
/// `canonical_apply` submodule.
#[path = "extensions/canonical_apply.rs"]
pub mod canonical_apply;
/// Shared-handle accessors for the completion match accumulators (Rust-original
/// glue restoring C's `matches = mgroup->lmatches` pointer alias; see the module
/// doc). Deliberately outside `src/ported/` — not a C-fn port.
pub mod comp_match_handles;
pub mod comp_word_tok;
/// `compile_zsh` submodule.
#[path = "extensions/compile_zsh.rs"]
pub mod compile_zsh;
/// `completion` submodule.
#[path = "extensions/completion.rs"]
pub mod completion;
/// `config` submodule.
#[path = "extensions/config.rs"]
pub mod config;
/// `cow_map` submodule — copy-on-write HashMap wrapper for cheap subshell
/// snapshot/restore (Rust-only helper).
#[path = "extensions/cow_map.rs"]
pub mod cow_map;
/// `daemon_presence` submodule.
#[path = "extensions/daemon_presence.rs"]
pub mod daemon_presence;
/// `errflag_cell` submodule — per-thread storage for `errflag`, restoring
/// the copy-on-fork semantics C zsh gets for free.
#[path = "extensions/errflag_cell.rs"]
pub mod errflag_cell;
/// `fast_hash` submodule — dependency-free FxHash for internal name tables.
#[path = "extensions/fast_hash.rs"]
pub mod fast_hash;
/// `thread_shell_state` submodule — per-thread storage for the state C
/// keeps per thread of execution (`scriptname`, `funcstack`,
/// `zsh_eval_context`, the diagnostic half of `locallevel`).
#[path = "extensions/thread_shell_state.rs"]
pub mod thread_shell_state;
/// `opts_cache` submodule — fast-path `isset()` option-state cache.
#[path = "extensions/opts_cache.rs"]
pub mod opts_cache;
/// `overlay_snapshot` submodule.
#[path = "extensions/overlay_snapshot.rs"]
pub mod overlay_snapshot;
/// `pat_cache` submodule — global compiled-pattern cache (Rust-only opt).
#[path = "extensions/pat_cache.rs"]
pub mod pat_cache;
/// `provenance` submodule — value-lineage ledger over bytecode
/// execution (zshrs-original; ported from stryke's `provenance.rs`).
#[path = "extensions/provenance.rs"]
pub mod provenance;
/// `reaped_status` submodule — the raw wait statuses the SIGCHLD reaper
/// collected, so a targeted `waitpid` that loses the race to it can
/// still read the status it needed (C never needs this: it has exactly
/// one collector).
#[path = "extensions/reaped_status.rs"]
pub mod reaped_status;
/// `script_cache` submodule.
#[path = "extensions/script_cache.rs"]
pub mod script_cache;
/// `stdout_ferror` submodule — the `ferror(stdout)` indicator for builtin
/// output, which `std::io::Stdout` cannot report for a closed fd 1.
#[path = "extensions/stdout_ferror.rs"]
pub mod stdout_ferror;
/// `shout` submodule — buffered terminal-output stream for the ZLE display
/// (the stdio buffering C gets from libc's `FILE *shout`).
#[path = "extensions/shout.rs"]
pub mod shout;
/// `startup_signals` submodule.
#[path = "extensions/startup_signals.rs"]
pub mod startup_signals;
/// `subexp_cleanup` submodule — RAII eviction of `__subexp_arr_*`
/// paramtab scratch temps created during array sub-expression expansion.
#[path = "extensions/subexp_cleanup.rs"]
pub mod subexp_cleanup;
/// `vm_pool` submodule — per-thread pool of recyclable fusevm VMs.
#[path = "extensions/vm_pool.rs"]
pub mod vm_pool;
// Daemon lives in the `zshrs-daemon` workspace crate. Re-export it as `daemon`
// so existing `crate::daemon::...` (in vm_helper) and `zsh::daemon::...` (in bins,
// integration tests) paths keep resolving without churn.
//
// The `daemon` feature gates the actual zshrs-daemon dep. When disabled
// (--no-default-features), a stub module covers the call sites in vm_helper.
// This lets the library compile in isolation while the daemon crate is
// being refactored in a concurrent session.
#[cfg(feature = "daemon")]
pub use zshrs_daemon as daemon;
/// `daemon` submodule.
#[cfg(not(feature = "daemon"))]
pub mod daemon {
    //! Stub module used when the `daemon` feature is disabled. Provides
    //! the minimal surface that `src/vm_helper` calls — the real
    //! implementation lives in the `zshrs-daemon` workspace crate.
    pub mod builtins {
        pub const ZSHRS_BUILTIN_NAMES: &[&str] = &[];
        /// `is_zshrs_builtin` — see implementation.
        pub fn is_zshrs_builtin(_name: &str) -> bool {
            false
        }
        /// `try_dispatch` — see implementation.
        pub fn try_dispatch(_name: &str, _argv: &[String]) -> Option<i32> {
            None
        }
        /// `dispatch` — see implementation.
        pub fn dispatch(_name: &str, _args: &[String]) -> Option<i32> {
            None
        }
    }
}
/// `ast_sexp` submodule.
#[path = "extensions/ast_sexp.rs"]
pub mod ast_sexp;
/// `bash_arrays` submodule — bash sparse-array holes tracker (Rust-only).
#[path = "extensions/bash_arrays.rs"]
pub mod bash_arrays;
/// `bash_prompt` submodule — bash `$PS1` backslash escapes (Rust-only).
#[path = "extensions/bash_prompt.rs"]
pub mod bash_prompt;
/// `emulation_output` submodule — per-shell builtin output formats (Rust-only).
#[path = "extensions/emulation_output.rs"]
pub mod emulation_output;
/// `emulation_startup` submodule — per-drop-in startup/logout files (Rust-only).
#[path = "extensions/emulation_startup.rs"]
pub mod emulation_startup;
/// `dap` submodule.
#[path = "extensions/dap.rs"]
pub mod dap;
/// `dash_mode` submodule — strict-dash emulation flag (Rust-only).
#[path = "extensions/dash_mode.rs"]
pub mod dash_mode;
/// `dumpers` submodule.
#[path = "extensions/dumpers.rs"]
pub mod dumpers;
/// `ext_builtins` submodule.
#[path = "extensions/ext_builtins.rs"]
pub mod ext_builtins;
/// `fds` submodule.
#[path = "extensions/fds.rs"]
pub mod fds;
/// `fish_features` submodule.
#[path = "extensions/fish_features.rs"]
pub mod fish_features;
/// `fmt` submodule — zsh source formatter (CLI `--fmt` + LSP
/// `textDocument/formatting`).
#[path = "extensions/fmt.rs"]
pub mod fmt;
/// `ftime` submodule — TEMPORARY per-function timing scaffold (Rust-only).
#[path = "extensions/ftime.rs"]
pub mod ftime;
/// `func_body_fmt` submodule.
#[path = "extensions/func_body_fmt.rs"]
pub mod func_body_fmt;
/// `funcdef_capture` submodule — Rust-only verbatim capture of function
/// body source text as `hgetc` consumes it, so `functions` / `typeset -f`
/// work for functions defined interactively or on stdin (where zshrs's
/// `LEX_INPUT` window does not exist). No C counterpart: C zsh
/// reconstructs the text from wordcode via `getpermtext` (Src/text.c:189).
#[path = "extensions/funcdef_capture.rs"]
pub mod funcdef_capture;
/// `global_rc` submodule — runtime sysconfdir resolution for the
/// system-wide startup files (Rust-only; zsh bakes the path in at build
/// time).
#[path = "extensions/global_rc.rs"]
pub mod global_rc;
/// `lsp` submodule.
#[path = "extensions/lsp.rs"]
pub mod lsp;
/// `lsp_symbols` submodule.
#[path = "extensions/lsp_symbols.rs"]
pub mod lsp_symbols;
/// `native_cmds` submodule — builtins contributed by the linking binary
/// (the fat `zshrs-native` build registers `git` / `arb` / `stryke` here).
#[path = "extensions/native_cmds.rs"]
pub mod native_cmds;
// Lexer + parser live in `src/ported/lex.rs` and `src/ported/parse.rs`.
// Re-export the modules so existing call sites (`zsh::lex::…`,
// `zsh::parse::…`, `zsh::tokens::…`) keep resolving.
// `tokens` aliases `lex` because tokens.rs's contents (lextok enum +
// reserved-word table) now live inside lex.rs. Char tokens (Pound / Inpar /
// Equals / …) and the REDIR_* / COND_* constants are not duplicated — they
// live as flat `pub const` items in `ported::zsh_h` per `Src/zsh.h:144-679`.
pub use ported::lex;
pub use ported::lex as tokens;
pub use ported::parse;
/// `heredoc_ast` submodule.
#[path = "extensions/heredoc_ast.rs"]
pub mod heredoc_ast;
/// `history` submodule.
#[path = "extensions/history.rs"]
pub mod history;
/// `history_lazy` submodule — on-demand HISTFILE paging; the history
/// is never slurped whole.
#[path = "extensions/history_lazy.rs"]
pub mod history_lazy;
/// `log` submodule.
#[path = "extensions/log.rs"]
pub mod log;
/// `startup_trace` submodule — phase timer for time-to-first-prompt work.
#[path = "extensions/startup_trace.rs"]
pub mod startup_trace;
/// `lowfd` submodule — keeps the shell's own descriptors out of the user's fd space.
#[path = "extensions/lowfd.rs"]
pub mod lowfd;
/// `zsh_ast` submodule.
#[path = "extensions/zsh_ast.rs"]
pub mod zsh_ast;
// Backwards-compat flat re-exports — call sites that still write
// `crate::datetime::…`, `crate::stat::…`, etc. resolve to the
// `crate::modules::<modname>` ports without churn. New code should
// reach for `crate::modules::<modname>` directly.
pub use builtins::sched;
pub use modules::attr;
pub use modules::cap;
pub use modules::clone;
pub use modules::curses;
pub use modules::datetime;
pub use modules::db_gdbm;
pub use modules::example;
pub use modules::files;
pub use modules::hlgroup;
pub use modules::ksh93;
pub use modules::langinfo;
pub use modules::mapfile;
pub use modules::mathfunc;
pub use modules::nearcolor;
pub use modules::newuser;
pub use modules::param_private;
pub use modules::parameter;
pub use modules::pcre;
pub use modules::random;
pub use modules::random_real;
pub use modules::regex as regex_module;
pub use modules::socket;
pub use modules::stat;
pub use modules::system;
pub use modules::tcp;
pub use modules::termcap;
pub use modules::terminfo;
pub use modules::watch;
pub use modules::zftp;
pub use modules::zprof;
pub use modules::zpty;
pub use modules::zselect;
pub use modules::zutil;
/// `compinit_bg` submodule.
#[path = "extensions/compinit_bg.rs"]
pub mod compinit_bg;
/// `fusevm_bridge` submodule.
pub mod fusevm_bridge;
/// `fusevm_disasm` submodule.
pub mod fusevm_disasm;
/// `intercepts` submodule.
#[path = "extensions/intercepts.rs"]
pub mod intercepts;
/// `p10k` submodule — native powerlevel10k prompt engine.
#[path = "extensions/p10k/mod.rs"]
pub mod p10k;
/// `pkg` — the `zpm` plugin package manager (global store).
#[path = "extensions/pkg/mod.rs"]
pub mod pkg;
/// `plugin_cache` submodule.
#[path = "extensions/plugin_cache.rs"]
pub mod plugin_cache;
/// `plugin_host` submodule — native (Rust) plugin loader (`zmodload -R`).
#[path = "extensions/plugin_host.rs"]
pub mod plugin_host;
/// `recorder_ext` submodule.
#[path = "extensions/recorder.rs"]
pub mod recorder_ext;
/// `rust_ffi` submodule — inline `rust { ... }` FFI desugaring.
pub mod rust_ffi;
// Plugin-Framework-Agnostic State-Modification Recorder. Entire module
// is `#![cfg(feature = "recorder")]` so it disappears from the default
// `zshrs` build at the rustc-expansion stage. See docs/RECORDER.md.
/// `async_precmd` submodule — run precmd-style hooks on the worker pool so they
/// don't block prompt rendering (writes into the shared param table).
#[path = "extensions/async_precmd.rs"]
pub mod async_precmd;
/// `autopair` submodule — native bracket/quote auto-pairing
/// (port of hlissner/zsh-autopair).
#[path = "extensions/autopair.rs"]
pub mod autopair;
/// `autosuggest` submodule — native fish-style autosuggestions
/// (port of the reader.rs autosuggestion state machine).
#[path = "extensions/autosuggest.rs"]
pub mod autosuggest;
/// `gen_docs` submodule.
#[path = "extensions/gen_docs.rs"]
pub mod gen_docs;
/// `history_search` submodule — native up-arrow prefix/substring/token history
/// search (port of fish reader/history_search.rs).
#[path = "extensions/history_search.rs"]
pub mod history_search;
/// `recorder` submodule.
#[cfg(feature = "recorder")]
pub mod recorder;
/// `regex_mod` submodule.
#[path = "extensions/regex_mod.rs"]
pub mod regex_mod;
/// `stringsort` submodule.
#[path = "extensions/stringsort.rs"]
pub mod stringsort;
/// `terminfo_caps` submodule — the frozen terminfo capability-name tables
/// that replace ncurses' exported `boolnames`/`numnames`/`strnames` arrays.
#[path = "extensions/terminfo_caps.rs"]
pub mod terminfo_caps;
/// `terminfo_db` submodule — pure-Rust reader for the compiled terminfo
/// database, replacing `setupterm`/`tigetstr`/`tgetent`/… from libtinfo.
#[path = "extensions/terminfo_db.rs"]
pub mod terminfo_db;
/// `tparm` submodule — the terminfo parameterized-string evaluator plus
/// `tgoto` and `tputs` padding, replacing the last libtinfo entry points.
#[path = "extensions/tparm.rs"]
pub mod tparm;
/// `syntax_highlight` submodule — native command-line syntax highlighting
/// (port of fish highlight/highlight.rs, driven by the zshrs lexer).
#[path = "extensions/syntax_highlight.rs"]
pub mod syntax_highlight;
/// `worker` submodule.
#[path = "extensions/worker.rs"]
pub mod worker;
/// `zle_file_tester` submodule — file-existence/permission tests for native ZLE
/// syntax highlighting (port of fish highlight/file_tester.rs).
#[path = "extensions/zle_file_tester.rs"]
pub mod zle_file_tester;
/// `zle_fx` submodule — wiring for the native ZLE effects (autosuggest,
/// syntax highlight, history search, autopair) into zlecore + the renderer.
#[path = "extensions/zle_fx.rs"]
pub mod zle_fx;
/// `zle_param_sync` submodule — ZLE special-param write-back sync
/// (Rust-only adapter for C's live GSU setters).
#[path = "extensions/zle_param_sync.rs"]
pub mod zle_param_sync;
/// `zsh_builtin_docs` submodule.
#[path = "extensions/zsh_builtin_docs.rs"]
pub mod zsh_builtin_docs;
/// `zsh_ext_builtin_docs` submodule.
#[path = "extensions/zsh_ext_builtin_docs.rs"]
pub mod zsh_ext_builtin_docs;
/// `zsh_keyword_docs` submodule.
#[path = "extensions/zsh_keyword_docs.rs"]
pub mod zsh_keyword_docs;
/// `zsh_option_docs` submodule.
#[path = "extensions/zsh_option_docs.rs"]
pub mod zsh_option_docs;
/// `zsh_special_var_docs` submodule.
#[path = "extensions/zsh_special_var_docs.rs"]
pub mod zsh_special_var_docs;
/// `ztest` submodule — shell-level unit test framework
/// (port of `../strykelang` test framework).
#[path = "extensions/ztest.rs"]
pub mod ztest;
/// `zwc` submodule.
#[path = "extensions/zwc.rs"]
pub mod zwc;
/// `zwc_decode` submodule.
#[path = "extensions/zwc_decode.rs"]
pub mod zwc_decode;
// Backwards-compat re-export so `crate::rlimits::…` keeps resolving.
pub use builtins::rlimits;

// Top-level shell executor state + fusevm bridge glue. Not a port of
// any single Src/*.c file — zsh's native wordcode VM lives in `Src/exec.c`;
// zshrs runs fusevm instead (see src/fusevm_bridge.rs).
/// `vm_helper` submodule.
pub mod vm_helper;

pub use fish_features::{
    autosuggest_from_history,
    colorize_line,
    expand_abbreviation,
    // Syntax highlighting
    highlight_shell,
    // Private mode
    is_private_mode,
    // Killring
    kill_add,
    kill_replace,
    kill_yank,
    kill_yank_rotate,
    set_private_mode,
    validate_autosuggestion,
    // Validation
    validate_command,
    with_abbrs,
    with_abbrs_mut,
    AbbrPosition,
    // Abbreviations
    Abbreviation,
    AbbreviationSet,
    // Autosuggestions
    Autosuggestion,
    HighlightRole,
    HighlightSpec,
    KillRing,
    ValidationStatus,
};
pub use tokens::lextok;
pub use vm_helper::ShellExecutor;

// ── Stryke integration hook ──
// The fat binary registers a handler for @ prefix dispatch.
// The thin binary leaves this as None — @ is treated as a normal character.

use std::sync::OnceLock;

type StrykeHandler = Box<dyn Fn(&str) -> i32 + Send + Sync>;
static STRYKE_HANDLER: OnceLock<StrykeHandler> = OnceLock::new();

/// Register a handler for @ prefix lines (fat binary sets this to stryke::run).
pub fn set_stryke_handler<F>(f: F)
where
    F: Fn(&str) -> i32 + Send + Sync + 'static,
{
    let _ = STRYKE_HANDLER.set(Box::new(f));
}

/// Try to dispatch a line starting with @ to stryke.
/// Returns Some(exit_code) if handled, None if no handler registered.
pub fn try_stryke_dispatch(code: &str) -> Option<i32> {
    STRYKE_HANDLER.get().map(|f| f(code))
}

/// Run an interactive `@ <code>` line through the registered stryke handler.
///
/// Called by `inputline` on each line it reads, before the lexer sees it:
/// stryke syntax is not shell syntax (`1:10 |> sum` is a pipe into a
/// redirect, `$_` would be expanded), so it cannot be parsed as a command
/// named `@`. Only the first line of an interactive command is considered,
/// so a `@` inside a continuation (heredoc body, open quote) stays shell
/// input. On dispatch `$?` takes the handler's status, the line is queued for
/// history (`stryke_history_flush`) unless HIST_IGNORE_SPACE drops it, and
/// the lexer is handed an empty line. Without a handler — the
/// thin binary — the line is returned untouched.
pub(crate) fn stryke_line(line: String) -> String {
    use crate::ported::zsh_h::{isset, HISTIGNORESPACE, SHINSTDIN};
    use std::sync::atomic::Ordering;

    if !(crate::ported::zsh_h::interact()
        && isset(SHINSTDIN)
        && crate::ported::lex::LEX_ISFIRSTLN.with(|c| c.get()))
    {
        return line;
    }
    let text = line.trim_end_matches('\n');
    let Some(code) = text.trim_start().strip_prefix('@') else {
        return line;
    };
    let code = code.trim();
    if code.is_empty() {
        return line;
    }
    let Some(status) = try_stryke_dispatch(code) else {
        return line;
    };
    crate::ported::builtin::LASTVAL.store(status, Ordering::SeqCst);
    if !(text.starts_with(' ') && isset(HISTIGNORESPACE)) {
        *STRYKE_HISTORY.lock().unwrap() = Some(text.to_string());
    }
    "\n".to_string()
}

/// A dispatched `@` line waiting to be recorded in history.
static STRYKE_HISTORY: std::sync::Mutex<Option<String>> = std::sync::Mutex::new(None);

/// Record the last dispatched `@` line in history, the way `print -s` does.
///
/// Called by `r#loop` between the `hend` that closed the `@` line's (empty)
/// event and the `hbegin` that opens the next one. Recording earlier, from
/// inside `inputline`, takes the event number `hbegin` already gave the
/// current line, and the duplicate number sends `fc -l` round the ring forever.
pub(crate) fn stryke_history_flush() {
    let Some(text) = STRYKE_HISTORY.lock().unwrap().take() else {
        return;
    };
    let event_id = crate::ported::hist::prepnexthistent();
    crate::ported::hashtable::addhistnode(&text, event_id as i32);
    let ent = crate::ported::hist::make_histent(event_id, text);
    if let Ok(mut ring) = crate::ported::hist::hist_ring.lock() {
        ring.insert(0, ent);
        crate::ported::hist::histlinect.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
    }
}

/// Register a native command contributed by the linking binary.
///
/// Convenience re-spelling of [`native_cmds::register`] at the crate root, so
/// a fat binary's `main` reads as one call per runtime:
///
/// ```ignore
/// zsh::register_native_command("git", |argv| zvcs::run_argv(argv));
/// ```
///
/// The name then dispatches in-process — `whence -w git` says `builtin`,
/// `${+builtins[git]}` is 1, `builtin git` reaches it, a user `git()` function
/// still shadows it, and `command git` still runs the one on `PATH`.
pub fn register_native_command<F>(name: &str, f: F)
where
    F: Fn(&[String]) -> i32 + Send + Sync + 'static,
{
    native_cmds::register(name, f);
}