@thigasdevelopment/luam 0.1.1 → 0.2.1

package/README.md

@@ -4,6 +4,12 @@
 
 <p align="center">Typed Lua for Multi Theft Auto. Compiles to plain Lua 5.1.</p>
 
+<p align="center">
+    <a href="https://thigasdevelopment.github.io/luam/"><b>Manual</b></a> ·
+    <a href="https://thigasdevelopment.github.io/luam/en/">English</a> ·
+    <a href="https://thigasdevelopment.github.io/luam/pt-br/">Português (Brasil)</a>
+</p>
+
 <p align="center">
     <a href="https://www.npmjs.com/package/@thigasdevelopment/luam"><img alt="npm" src="https://img.shields.io/npm/v/@thigasdevelopment/luam?color=cb3837&label=npm"></a>
     <img alt="Target" src="https://img.shields.io/badge/target-Lua%205.1-000080">
@@ -38,6 +44,10 @@ before the server ever starts. A build with any error writes nothing.
 
 ## Install
 
+> Full instructions, including `PATH` troubleshooting:
+> **[Installation](https://thigasdevelopment.github.io/luam/en/guide/installation)**
+> · [Instalação](https://thigasdevelopment.github.io/luam/pt-br/guide/installation)
+
 You need [Node.js](https://nodejs.org/) 20 or newer and an
 [MTA:SA](https://multitheftauto.com/) 1.5+ server. No Lua toolchain — the
 compiler emits Lua text, it never runs it.
@@ -114,12 +124,29 @@ bin directory is not on your `PATH`.
 
 The VS Code extension gives you types, completion and errors while you type —
 from the same checker the CLI runs, so the editor and the build never disagree.
-See [Editor support](#editor-support) below for how to install it.
+Let the CLI detect supported editors and ask before changing each one:
+
+```bash
+luam setup
+```
+
+For an unattended development-machine setup, approve every detected editor:
+
+```bash
+luam setup --yes
+```
+
+Run `luam doctor` afterward to check the CLI, detected editors, and extension.
+See [Editor support](#editor-support) for the compatibility matrix and manual installation.
 
 ---
 
 ## Quick start
 
+> Step by step, with a checked example:
+> **[Quick start](https://thigasdevelopment.github.io/luam/en/guide/quick-start)**
+> · [Início rápido](https://thigasdevelopment.github.io/luam/pt-br/guide/quick-start)
+
 **1. Scaffold.** `init` writes exactly one file, `luam.json`. No framework, no
 example tree, nothing to delete.
 
@@ -203,8 +230,12 @@ luam dev
 
 ## The CLI
 
-Five commands. Every one of them reads `luam.json` from the current directory,
-or from `--cwd`.
+> Every command, option and exit code:
+> **[CLI commands](https://thigasdevelopment.github.io/luam/en/tooling/cli)**
+> · [Comandos da CLI](https://thigasdevelopment.github.io/luam/pt-br/tooling/cli)
+
+Project commands read `luam.json` from the current directory or from `--cwd`.
+`setup`, `doctor`, and `init` do not require an existing project.
 
 ### `luam init`
 
@@ -217,6 +248,29 @@ luam init --name gamemode-race
 
 An existing `luam.json` is kept and reported — pass `--force` to overwrite it.
 
+### `luam setup`
+
+Detects supported editor commands on `PATH`, asks for consent, and installs the
+Luam extension. It tries the editor's marketplace first and falls back to the
+official `.vsix` from the GitHub release that matches the CLI version.
+
+```bash
+luam setup
+luam setup --yes
+```
+
+The command never installs into an editor silently. In CI or another
+non-interactive terminal, pass `--yes` explicitly.
+
+### `luam doctor`
+
+Reports the running CLI and Node.js versions, every supported editor detected
+on `PATH`, and whether that editor has the Luam extension.
+
+```bash
+luam doctor
+```
+
 ### `luam check`
 
 Compiles everything and prints diagnostics. **Writes nothing.** This is the
@@ -233,7 +287,9 @@ Build failed: 1 error, 0 warnings in 4 ms.
 
 ### `luam build`
 
-Compiles and writes the resource into `<outDir>/<name>`.
+Compiles and writes the bundled production resource into `<outDir>/<name>`, plus
+`<outDir>/<name>.luam-map.json` for resolving production error positions. Pass
+`--no-bundle` for tree output or `--no-map` to suppress the map.
 
 ```bash
 luam build
@@ -337,6 +393,9 @@ a deploy script wants.
 | `--name <name>` | Resource name for `init` |
 | `--force` | Let `init` overwrite a file that exists |
 | `--watch` / `--no-watch` | Keep `ensure` or `dev` watching, or run it once. Both watch by default |
+| `--bundle` / `--no-bundle` | Select bundle or tree output for `build` and `ensure`; `dev` always uses tree |
+| `--no-map` | Disable source position maps |
+| `--map <path>` | Select the resource map for `luam trace` |
 | `--offline` | Skip the `min_mta_version` lookup. `LUAM_OFFLINE` does the same |
 | `--no-color` | Plain output, no colour or emoji. `NO_COLOR` does the same |
 | `-h`, `--help` | Print the usage text |
@@ -364,6 +423,8 @@ Only `name` is required.
 | `assetDirs` | `["assets"]` | Copied verbatim and declared `<file>`, so clients download them |
 | `outDir` | `"build"` | Receives `<outDir>/<name>` |
 | `loadOrder` | `[]` | Source paths pinned ahead of their group in `meta.xml`. An entry matching no file fails the build |
+| `output.bundle` | `true` | Default `build` layout; command flags override it |
+| `output.map` | `true` | Generate source position maps; only `build` writes one to disk |
 | `oop` | `false` | Enables the MTA OOP API (`player:getName()`) and writes `<oop>true</oop>` |
 | `helpers` | `[]` | Runtime helpers to copy even when no feature requires them |
 | `serverPath` | unset | MTA server root, for `ensure` |
@@ -375,12 +436,20 @@ Paths must stay inside their base directory — an absolute path or a `..` segme
 is rejected.
 
 Every field, the transport in detail, `.env` handling and declaration files:
-**[`packages/cli/README.md`](packages/cli/README.md)**.
+**[luam.json](https://thigasdevelopment.github.io/luam/en/tooling/luam-json)**
+and
+[Configuration fields](https://thigasdevelopment.github.io/luam/en/reference/configuration-fields)
+· [luam.json](https://thigasdevelopment.github.io/luam/pt-br/tooling/luam-json)
+· also in [`packages/cli/README.md`](packages/cli/README.md).
 
 ---
 
 ## The language
 
+> Every feature, with emitted Lua and the errors it catches:
+> **[The language](https://thigasdevelopment.github.io/luam/en/language/)**
+> · [A linguagem](https://thigasdevelopment.github.io/luam/pt-br/language/)
+
 ```lua
 local name: string = 'Thigas'
 local player: Player? = nil          # optional
@@ -424,13 +493,18 @@ local vip = new VIPPlayer('Thigas', 2)
 | `export` | Erased from the Lua, written into `meta.xml` as `<export function="f" />` |
 | Native libraries | `sleep` plus the `Threads`, `Async` and `Dotenv` classes, injected only when named |
 | Native classes | `local tasks = new Async(100)` — same `new` as a project class |
+| MTA OOP classes | `Player.getRandom()`, `File.exists(path)`, and callable constructors such as `File(path)` |
 | Deployment values | `.env` keys typed and reachable as `env.SERVER_NAME`, server-only |
 | Strictness | `#!strict` (default), `#!nonstrict`, `#!nocheck` per file |
 
-`class`, `interface`, `enum`, `new`, `fun` and `export` are contextual keywords —
-existing Lua that uses them as identifiers keeps compiling. Reach for
-`#!nocheck` when porting existing Lua: rename to `.luam` and the build passes
-while you annotate module by module.
+`class`, `constructor`, `declare`, `enum`, `export`, `extends`, `implements`,
+`interface`, `new` and `type` are **reserved**, on top of the 21 Lua 5.1
+keywords. Existing Lua that uses one as an identifier needs a rename — but a
+property name still works (`config.type`), and `type(value)` keeps working
+because `type` stays callable. `fun` is the one term that stays contextual.
+
+Reach for `#!nocheck` when porting existing Lua: rename to `.luam` and the build
+passes while you annotate module by module.
 
 ### Environments
 
@@ -451,31 +525,38 @@ a build.
 
 The catalog ships **1294 MTA declarations**, **203 events**, **57 element types**
 and the Lua standard library, generated from the MTA wiki — plus the OOP surface
-(**57 classes, 652 methods**) behind `"oop": true`.
+(**57 classes, 652 methods, 118 static methods, 46 constructors**) behind
+`"oop": true`.
+
+`File(path)` opens an existing file read/write and creates it when missing.
+Use `File.new(path)` only for destructive creation because it truncates an
+existing file. Use `fileOpen(path, true)` when read-only access is required.
 
 ---
 
 ## What you get out
 
 ```
-build/my-resource/
-├── meta.xml          generated: scripts typed by environment, helpers first
-├── config.lua        copied verbatim, yours to edit
-├── .env              written once, never overwritten
-├── lib/shared/class.lua
-└── src/
-    ├── shared/config.lua
-    ├── server/main.lua
-    └── client/hud.lua
+build/
+├── my-resource.luam-map.json
+└── my-resource/
+    ├── meta.xml
+    ├── config.lua
+    ├── .env
+    ├── assets/
+    └── src/
+        ├── shared.lua
+        ├── server.lua
+        └── client.lua
 ```
 
-The output mirrors the tree you authored, changing only the extension, so a path
-in an MTA error maps straight back to a source file. Runtime helpers land in
-`lib/<environment>` and are copied **only when the generated code uses the
-feature** — a resource with no classes never carries `class.lua`.
+`build` ships at most one bundle per non-empty environment. `config.lua`, `.env`,
+and assets remain unbundled at their stable paths, and the map remains outside
+the resource. `ensure` defaults to a mirrored tree and `dev` always uses one.
+Use `luam trace src/server.lua:42` with the matching map to recover the authored
+file, line, and symbol. See [output layouts and source maps](https://thigasdevelopment.github.io/luam/en/reference/output-layouts).
 
-`meta.xml` uses one wildcard per environment, so adding a module leaves it byte
-identical. `min_mta_version` is resolved from the latest MTA release and cached;
+`min_mta_version` is resolved from the latest MTA release and cached;
 with no network and no cache it is omitted with a warning, and the build still
 succeeds.
 
@@ -483,6 +564,10 @@ succeeds.
 
 ## Editor support
 
+> Compatibility matrix, manual `.vsix` install, settings:
+> **[Editors](https://thigasdevelopment.github.io/luam/en/tooling/editors)**
+> · [Editores](https://thigasdevelopment.github.io/luam/pt-br/tooling/editors)
+
 The **Luam** extension for VS Code starts a language server built on the same
 frontend the CLI uses, so the editor and the build never disagree about a file.
 
@@ -491,7 +576,7 @@ frontend the CLI uses, so the editor and the build never disagree about a file.
 | Syntax highlighting | `.luam` files, including type annotations and template strings |
 | Diagnostics | On open and on every keystroke, cleared when you fix the file |
 | Completion | Scope symbols, workspace globals, MTA APIs scoped to the file's environment, keywords |
-| Member completion | `.` and `:` complete class fields and methods (inherited too), enum members, and native extensions |
+| Member completion | `.` completes fields and static methods; `:` completes instance methods, including inherited MTA members |
 | Hover | Declared or inferred type, function signature, and the environment of an MTA API |
 | Navigation | Go to definition, find references, rename — across files for globals |
 
@@ -500,17 +585,40 @@ server file, `kickPlayer` never appears in a client file.
 
 ### Installing it
 
-The extension is not on the Marketplace yet, so install the `.vsix` by hand.
+**Through the CLI (recommended).** The command detects all supported editors
+whose launchers are on `PATH` and asks before installing:
 
-**From a release (easiest).** Download `luam-<version>.vsix` from the
-[Releases page](https://github.com/ThigasDevelopment/luam/releases), then:
+```bash
+luam setup
+```
+
+| Editor | Launcher detected | Automatic installation | Distribution path |
+| --- | --- | --- | --- |
+| Visual Studio Code | `code` | Yes | Marketplace, then release `.vsix` fallback |
+| Visual Studio Code Insiders | `code-insiders` | Yes | Marketplace, then release `.vsix` fallback |
+| Cursor | `cursor` | Yes | Editor marketplace, then release `.vsix` fallback |
+| VSCodium | `codium` | Yes | Open VSX when available, then release `.vsix` fallback |
+| Windsurf | `windsurf` | Yes | Editor marketplace, then release `.vsix` fallback |
+
+Other VS Code-compatible forks can usually install the release `.vsix`
+manually, but `luam setup` does not claim support until their launcher and
+extension APIs are stable. JetBrains IDEs need a separate plugin and are not
+supported by this VS Code extension. Neovim, Zed, and Sublime Text need their
+own LSP adapter or extension and are not currently supported.
+
+**From a release.** Download `luam-<version>.vsix` from the
+[Releases page](https://github.com/ThigasDevelopment/luam/releases), then use
+the launcher for your editor:
 
 ```bash
 code --install-extension luam-0.1.1.vsix
+cursor --install-extension luam-0.1.1.vsix
+codium --install-extension luam-0.1.1.vsix
+windsurf --install-extension luam-0.1.1.vsix
 ```
 
-Or in VS Code: **Extensions** → **⋯** menu → **Install from VSIX…** → pick the
-file. Reload the window when it asks.
+In a compatible editor, you can also open **Extensions**, choose **Install from
+VSIX**, and select the downloaded file. Reload the window when prompted.
 
 **From source.** Build the VSIX yourself:
 
@@ -561,6 +669,10 @@ node packages/lsp/dist/luam-lsp.mjs --stdio
 
 ## Known limitations
 
+> With the workaround for each:
+> **[Limitations](https://thigasdevelopment.github.io/luam/en/reference/limitations)**
+> · [Limitações](https://thigasdevelopment.github.io/luam/pt-br/reference/limitations)
+
 - **No type narrowing.** `if value ~= nil then` does not refine `string?`.
 - **Declaration order matters for classes within a file.** `extends` and `new`
   resolve against classes declared earlier in the same file.
@@ -598,6 +710,23 @@ Each package documents itself: [`cli`](packages/cli/README.md),
 [`template`](packages/template/README.md). Released milestones and their changes
 are in the [changelog](CHANGELOG.md).
 
+### The manual
+
+The user-facing manual lives in [`docs/`](docs/) and is published to
+[thigasdevelopment.github.io/luam](https://thigasdevelopment.github.io/luam/).
+
+```bash
+pnpm docs:dev       # local preview with hot reload
+pnpm docs:verify    # locale parity, snippet checks, and a full build
+```
+
+English is the source locale and pt-BR is translated from it; every page exists in
+both, and CI fails when one is missing. Code samples are real files under
+`docs/snippets/`, verified with `luam check` on every documentation build, and
+rendered into both locales from the same source — so a sample cannot drift. See
+the [documentation changelog](https://thigasdevelopment.github.io/luam/en/changelog)
+for the conventions.
+
 ---
 
 ## Acknowledgments