About this project

Block is a local-first polyglot programming language and execution engine that lets developers compose workflows across multiple host runtimes within a single readable document. Instead of stitching Python, JavaScript, Lua, PHP, SQL, Ruby, PowerShell, and other languages together with shell scripts or temporary files, Block uses a tag-based syntax (`<py>`, `<js>`, `<sql>`, etc.) where each language block retains its native syntax while Block manages sequential execution, serialization, and state transfer across process boundaries. ### How It Works A Block document is parsed, validated, and then each language stage is launched as a separate host process. Block passes a prepared representation of shared serializable state from one stage to the next. This means open file handles, sockets, live database connections, and circular references cannot be passed between blocks—only plain data types like integers, floats, strings, booleans, arrays, and dictionaries. The process-boundary model makes workflows inspectable and portable but requires deliberate state design. ### Editions and File Formats Three editions are available: - **Lite** (`.blkl`): Lightweight local polyglot scripts with basic language blocks. - **Standard** (`.blk`): General development use, adding imports, project discovery, native control flow, and local server support. - **Plus** (`.blkp`): Full feature surface including custom runtime definitions, formatting, linting, documentation generation, and extended integrations. Executable commands map to editions: `block-lite`, `block`, and `block-plus`. ### Supported Languages Block delegates to host runtimes found on PATH. Common tags include `<py>` for Python, `<js>` for JavaScript/Node.js, `<php>`, `<lua>`, `<ruby>`, `<ps>` for PowerShell, `<sql>` for SQLite, `<html>` and `<json>` for templated output, plus `<go>`, `<rust>`, `<zig>`, `<ts>`, `<cs>`, `<kotlin>`, `<dart>`, `<perl>`, `<r>`, `<c>`, and `<cpp>` where compilers are available. Not all tags are enabled in every edition. ### Shared State Pipeline The central feature is serializable state passed between blocks: ```block <py> total = 40 + 2 </py> <js> console.log(total); </js> <html> <p>Total: {{total}}</p> </html> ``` Values produced in one block become available in the next. Best practice is to produce a small explicit result object rather than relying on every local variable being exported. ### Native Block Control Flow All editions include a deterministic, sandboxed native language core supporting assignments, `if`/`elif`/`else`, `while` and `for` loops, `range()`, functions, list and dictionary literals, indexing, and built-in functions like `len`, `str`, `int`, `sum`, and `keys`. This core intentionally lacks file, network, process, or package APIs—use a host runtime block when those are needed. ### Local HTTP Server Standard and Plus editions can declare routes and static file serving: ```block <server port="8080"> <route path="/hello"> <py> message = "hello from Block" </py> <json> {"message": "{{message}}"} </json> </route> </server> ``` Routes require an `X-Api-Token` header by default. This server is designed for local development only. ### Project Management Projects are initialized with `block project init` and managed via `block.project.json`. A workspace root can be configured once for multi-project setups. Imports use relative paths with sandboxed directory limits, recursion depth caps, and circular-import detection. ### CLI Commands Key commands include `block <file>` to execute, `block check <file>` to parse without running, `block plan --json` for read-only execution previews, `block errors` for diagnostic codes, `block ast` for structured syntax trees, `block runtimes` to detect installed hosts, `block doctor` for environment diagnostics, and `block-plus fmt/doc` for formatting and documentation in Plus. ### Security and Sandboxing Imports are confined to sandboxed directories with file count and size limits. Directory traversal via `../` outside the project root is blocked. PowerShell execution is disabled by default in new configurations. The native control flow core is read-only with no file or network access. The secure installer validates SHA-256 checksums and never invokes Winget, Chocolatey, or downloaded scripts. ### Editor Support VS Code extension and Acode plugin are available. The editor extensions recognize `.block`, `.blocklite`, and `.blockplus` aliases in addition to the primary extensions. ### Release and Build Current release is 2.7.5. The Windows build compiles from C# source using the .NET Framework compiler via `build.ps1`, producing `block.exe`, `block-lite.exe`, and `block-plus.exe`. Free code signing is provided by SignPath.io; current Windows releases are pending review and unsigned. ### What Block Is Not Block is not a replacement for Python, JavaScript, Rust, or any mature language. It does not emulate their syntax or bundle host runtimes. It coordinates local runtimes and makes the data boundary between stages visible. Parser errors belong to Block; missing runtimes, package errors, and language-specific issues belong to the host environment. ### License MIT license. Repository source, documentation, and examples are all open.