turbo-editors/turbo-js · README.md

⑂ main

README.md · 115 lines · 10.3 KBmarkdown    Blame HistoryRaw
   1
3A Turbo C-style editor for JavaScript on Node.js, written in Go.
5Built on **[turbo-core](https://rickub.com/turbo-editors/turbo-core)**, the library every Turbo editor shares. What is in this repository is the command, the profile that says this editor is for JavaScript, a JavaScript scanner and a JSON one — about twelve hundred lines. Everything else lives in the library.
7A full-screen terminal IDE with the Borland furniture — a menu bar with hot keys, movable windows that cast shadows, modal dialogs, a clickable status bar — and the things a Node editor needs today: syntax colouring that knows regular expressions, template literals, private fields and Node's globals, loadable colour themes, completion and diagnostics from `typescript-language-server`, shell windows, per-project settings, a project tree, snippets, windows onto coding agents, and the Node toolchain a menu away.
10 File  Edit  Search  Run  Code  Options  Window  Snippets  Agent  JavaScript  Help
11╔═[x]═══════════════════════════════════════ main.js ═══════════════════════════1═[■]╗
12║ 1 #!/usr/bin/env node                                                          ▲║
13║ 2 // Greets whoever is named on the command line, or JavaScript.               ▓║
14║ 3 import { argv } from "node:process";                                         ░║
15║ 4 import { Greeter } from "./greeter.js";                                      ░║
17║ 6 const who = argv[2] ?? "JavaScript";                                         ░║
18║ 7 new Greeter(who).greet(3);                                                   ▼║
19║◄▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░►║
20╚═════════════════════════════════════════════════════════════════════════════════╝
21 F1 Describe  F2 Save  F3 Open  F6 Window  F7 Next  F10 Menu  Alt-X Exit  1:1  LSP: ready
24## Getting started
27make install
30That builds the editor, puts it where your shell looks for commands, and reports what it found — the Go version it built with, where the binary went, whether that directory is on your `PATH`, and whether `typescript-language-server` is installed. Then, from any Node project:
33turbo-js main.js
36To build without installing, `make build` leaves the binary in `bin/turbo-js`. From the module proxy instead of a checkout: `go install rickub.com/turbo-editors/turbo-js@latest`.
38For completion, install the language server as well — the editor works without it, and says so on the status bar:
41npm install -g typescript-language-server typescript@6
44The `@6` is not optional: TypeScript 7 ships no `tsserver.js`, and the server refuses to start beside it. `make install` with `--with-server` — `scripts/install.sh --with-server` — runs that line for you.
46The [tutorial](docs/en/tutorials/getting-started.md) walks through a first session in about ten minutes, and [`demos/greeter`](demos/) is a small project to open once you have the editor.
48## Features
50- **Every build knows what it is** — `turbo-js -version` and **Help ▸ About** name the version, the commit and the build date, stamped in by the linker from `git describe` rather than read from a constant somebody forgot to bump
51- **Turbo Vision interface** — menu bar with `Alt`-letter hot keys, overlapping movable and resizable windows, modal dialogs, mouse support throughout
52- **Syntax colouring for nine languages** — JavaScript by a hand-written scanner that knows regular expressions, template literals across lines, the hashbang line, private `#fields`, decorators and Node's globals; JSON with keys told from values; plus TOML, YAML, Markdown, HTML, XML, Dockerfiles and shell scripts from turbo-core
53- **Themes** in TOML, eleven embedded — Borland navy, dark grey, paper white, espresso, Catppuccin Frappé and Latte, cobalt, Darcula and IntelliJ Light, and a hueless monochrome in both polarities — and any number of your own, with inheritance between files and between style keys. Every shipped theme is held to its contrast by tests
54- **Per-project settings** in `.turbo-js/settings.toml` — pin a theme, turn on automatic saving — created from a menu item and never by itself, and re-read every time you save it
55- **Completion, hover, definitions, references, implementations, symbols and diagnostics** from `typescript-language-server`, all nine questions answered for plain JavaScript, entirely optional
56- **Terminal windows** — `F8` opens a real shell in a window, with its own VT/ANSI emulator, scrollback and job control (Linux, macOS and Windows)
57- **Project tree** — `F9` shows the project's files in a window; walk it with the arrows and press Enter to open one
58- **Snippets** — a `Snippets` menu built from `.turbo-js/snippets.toml`, grouped into submenus and filtered by the file you are in; the chosen text is inserted at the cursor, re-indented to match
59- **The Node toolchain a menu away** — `Alt-J` runs `npm install`, `npx prettier --write .`, `npx eslint .`, `node --test`, `node <script>` and `npm start` from `.turbo-js/tools.toml`, each showing its output where the tool asked: a popup that fills in as it goes, a terminal window, or an editing window to search. Files the command rewrote are re-read for you, and a tool naming a `menu` of its own gets that menu on the bar
60- **Agent windows** — `Alt-A` opens a conversation with a coding agent that speaks the Agent Client Protocol, configured in `.turbo-js/acp.toml`; the code it sends in a ```js fence is coloured by the same scanner as your files, and copies straight out of the conversation
61- **Editing** with word movement, block indent, a shared clipboard, and undo that merges a run of typing into one step
62- **Faithful files** — line endings and the trailing newline are preserved, and saving is atomic
63- **Automatic saving**, off by default, writing a short while after you stop typing
65## Commands
67| Command | What it does |
68| --- | --- |
69| `make install` | Build and install onto your `PATH` |
70| `make build` | Compile into `bin/turbo-js` |
71| `make test` | Run the whole test suite |
72| `make check` | `fmt`, `vet`, then the tests — what a commit should pass |
73| `make run FILE=main.js` | Build and start the editor on a file |
74| `make help` | List every target |
77turbo-js [-theme name] [-no-lsp] [file...]
78turbo-js -list-themes
81## Documentation
83Full documentation in **[English](docs/en/)** and **[French](docs/fr/)**, organised by the [Diátaxis](https://diataxis.fr) method:
86| --- | --- |
87| **Tutorial** | [Your first Node program in Turbo JS](docs/en/tutorials/getting-started.md) |
88| **How-to** | [install](docs/en/how-to/install.md) · [install Node.js](docs/en/how-to/install-node.md) · [run the tests](docs/en/how-to/run-the-tests.md) · [enable completion](docs/en/how-to/enable-completion.md) · [write a theme](docs/en/how-to/write-a-theme.md) · [move around a file](docs/en/how-to/navigate-code.md) · [ask about code](docs/en/how-to/ask-about-code.md) · [use a terminal](docs/en/how-to/use-a-terminal.md) · [configure a project](docs/en/how-to/configure-a-project.md) · [browse a project](docs/en/how-to/browse-a-project.md) · [use snippets](docs/en/how-to/use-snippets.md) · [run Node commands](docs/en/how-to/run-node-commands.md) · [talk to an agent](docs/en/how-to/talk-to-an-agent.md) · [make a release](docs/en/how-to/make-a-release.md) |
89| **Reference** | [command line](docs/en/reference/cli.md) · [keyboard](docs/en/reference/keyboard.md) · [menus](docs/en/reference/menus.md) · [theme format](docs/en/reference/themes.md) · [terminal windows](docs/en/reference/terminal.md) · [project settings](docs/en/reference/project-settings.md) · [project tree](docs/en/reference/project-tree.md) · [languages](docs/en/reference/languages.md) · [snippets](docs/en/reference/snippets.md) · [JavaScript tools](docs/en/reference/javascript-tools.md) · [agents and ACP](docs/en/reference/acp.md) · [the version number](docs/en/reference/versioning.md) |
90| **Explanation** | [architecture](docs/en/explanation/architecture.md) · [design decisions](docs/en/explanation/design-decisions.md) · [colouring and completion](docs/en/explanation/colouring-and-completion.md) · [terminal windows](docs/en/explanation/terminal-windows.md) · [project settings](docs/en/explanation/project-settings.md) · [project tree](docs/en/explanation/project-tree.md) · [snippets](docs/en/explanation/snippets.md) · [JavaScript tools](docs/en/explanation/javascript-tools.md) · [agent windows](docs/en/explanation/agent-windows.md) |
92The library's packages each carry their own `README.md` beside the code, in [turbo-core](https://rickub.com/turbo-editors/turbo-core).
94## Where the code is
97| --- | --- |
98| `main.go` | flags, the terminal, the wiring |
99| `internal/jslang` | the profile, the JavaScript and JSON scanners, the four starter files |
100| `demos/` | a small Node project to open in the editor |
101| everything else | [turbo-core](https://rickub.com/turbo-editors/turbo-core) |
103The dependency graph is drawn in [`docs/diagrams/packages.drawio`](docs/diagrams/packages.drawio), checked against `go list`.
105## Design in one line
107Two dependencies — `tcell/v2` and `BurntSushi/toml` — and everything else from the standard library, including the Language Server Protocol client. Both come through turbo-core; this repository adds none of its own. The [design decisions](docs/en/explanation/design-decisions.md) page explains why.
109## Requirements
111Go 1.26 or later to build it — the editor is written in Go even though it is an editor for JavaScript. A terminal with mouse reporting, which is all of them. Node and npm for the JavaScript menu; `typescript-language-server` with `typescript@6` for completion. All three are optional.
113
115The other editors in the family are MIT-licensed; this repository's licence file is the owner's to add.

📦 Turbo JS 91999d1 k33g 9h ago	1	# turbo-js
	2
	3	A Turbo C-style editor for JavaScript on Node.js, written in Go.
	4
	5	Built on [turbo-core](https://rickub.com/turbo-editors/turbo-core), the library every Turbo editor shares. What is in this repository is the command, the profile that says this editor is for JavaScript, a JavaScript scanner and a JSON one — about twelve hundred lines. Everything else lives in the library.
	6
	7	A full-screen terminal IDE with the Borland furniture — a menu bar with hot keys, movable windows that cast shadows, modal dialogs, a clickable status bar — and the things a Node editor needs today: syntax colouring that knows regular expressions, template literals, private fields and Node's globals, loadable colour themes, completion and diagnostics from `typescript-language-server`, shell windows, per-project settings, a project tree, snippets, windows onto coding agents, and the Node toolchain a menu away.
	8
	9	```
	10	File Edit Search Run Code Options Window Snippets Agent JavaScript Help
	11	╔═[x]═══════════════════════════════════════ main.js ═══════════════════════════1═[■]╗
	12	║ 1 #!/usr/bin/env node ▲║
	13	║ 2 // Greets whoever is named on the command line, or JavaScript. ▓║
	14	║ 3 import { argv } from "node:process"; ░║
	15	║ 4 import { Greeter } from "./greeter.js"; ░║
	16	║ 5 ░║
	17	║ 6 const who = argv[2] ?? "JavaScript"; ░║
	18	║ 7 new Greeter(who).greet(3); ▼║
	19	║◄▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░►║
	20	╚═════════════════════════════════════════════════════════════════════════════════╝
	21	F1 Describe F2 Save F3 Open F6 Window F7 Next F10 Menu Alt-X Exit 1:1 LSP: ready
	22	```
	23
	24	## Getting started
	25
	26	```bash
	27	make install
	28	```
	29
	30	That builds the editor, puts it where your shell looks for commands, and reports what it found — the Go version it built with, where the binary went, whether that directory is on your `PATH`, and whether `typescript-language-server` is installed. Then, from any Node project:
	31
	32	```bash
	33	turbo-js main.js
	34	```
	35
	36	To build without installing, `make build` leaves the binary in `bin/turbo-js`. From the module proxy instead of a checkout: `go install rickub.com/turbo-editors/turbo-js@latest`.
	37
	38	For completion, install the language server as well — the editor works without it, and says so on the status bar:
	39
	40	```bash
	41	npm install -g typescript-language-server typescript@6
	42	```
	43
	44	The `@6` is not optional: TypeScript 7 ships no `tsserver.js`, and the server refuses to start beside it. `make install` with `--with-server` — `scripts/install.sh --with-server` — runs that line for you.
	45
	46	The [tutorial](docs/en/tutorials/getting-started.md) walks through a first session in about ten minutes, and [`demos/greeter`](demos/) is a small project to open once you have the editor.
	47
	48	## Features
	49
	50	- Every build knows what it is — `turbo-js -version` and Help ▸ About name the version, the commit and the build date, stamped in by the linker from `git describe` rather than read from a constant somebody forgot to bump
	51	- Turbo Vision interface — menu bar with `Alt`-letter hot keys, overlapping movable and resizable windows, modal dialogs, mouse support throughout
	52	- Syntax colouring for nine languages — JavaScript by a hand-written scanner that knows regular expressions, template literals across lines, the hashbang line, private `#fields`, decorators and Node's globals; JSON with keys told from values; plus TOML, YAML, Markdown, HTML, XML, Dockerfiles and shell scripts from turbo-core
	53	- Themes in TOML, eleven embedded — Borland navy, dark grey, paper white, espresso, Catppuccin Frappé and Latte, cobalt, Darcula and IntelliJ Light, and a hueless monochrome in both polarities — and any number of your own, with inheritance between files and between style keys. Every shipped theme is held to its contrast by tests
	54	- Per-project settings in `.turbo-js/settings.toml` — pin a theme, turn on automatic saving — created from a menu item and never by itself, and re-read every time you save it
	55	- Completion, hover, definitions, references, implementations, symbols and diagnostics from `typescript-language-server`, all nine questions answered for plain JavaScript, entirely optional
	56	- Terminal windows — `F8` opens a real shell in a window, with its own VT/ANSI emulator, scrollback and job control (Linux, macOS and Windows)
	57	- Project tree — `F9` shows the project's files in a window; walk it with the arrows and press Enter to open one
	58	- Snippets — a `Snippets` menu built from `.turbo-js/snippets.toml`, grouped into submenus and filtered by the file you are in; the chosen text is inserted at the cursor, re-indented to match
	59	- The Node toolchain a menu away — `Alt-J` runs `npm install`, `npx prettier --write .`, `npx eslint .`, `node --test`, `node <script>` and `npm start` from `.turbo-js/tools.toml`, each showing its output where the tool asked: a popup that fills in as it goes, a terminal window, or an editing window to search. Files the command rewrote are re-read for you, and a tool naming a `menu` of its own gets that menu on the bar
	60	- Agent windows — `Alt-A` opens a conversation with a coding agent that speaks the Agent Client Protocol, configured in `.turbo-js/acp.toml`; the code it sends in a ```js fence is coloured by the same scanner as your files, and copies straight out of the conversation
	61	- Editing with word movement, block indent, a shared clipboard, and undo that merges a run of typing into one step
	62	- Faithful files — line endings and the trailing newline are preserved, and saving is atomic
	63	- Automatic saving, off by default, writing a short while after you stop typing
	64
65	## Commands
66
67	\| Command \| What it does \|
68	\| --- \| --- \|
69	\| `make install` \| Build and install onto your `PATH` \|
70	\| `make build` \| Compile into `bin/turbo-js` \|
71	\| `make test` \| Run the whole test suite \|
72	\| `make check` \| `fmt`, `vet`, then the tests — what a commit should pass \|
73	\| `make run FILE=main.js` \| Build and start the editor on a file \|
74	\| `make help` \| List every target \|
75
76	```bash
77	turbo-js [-theme name] [-no-lsp] [file...]
78	turbo-js -list-themes
79	```
80
81	## Documentation
82
83	Full documentation in [English](docs/en/) and [French](docs/fr/), organised by the [Diátaxis](https://diataxis.fr) method:
84
85	\| \| \|
86	\| --- \| --- \|
87	\| Tutorial \| [Your first Node program in Turbo JS](docs/en/tutorials/getting-started.md) \|
88	\| How-to \| [install](docs/en/how-to/install.md) · [install Node.js](docs/en/how-to/install-node.md) · [run the tests](docs/en/how-to/run-the-tests.md) · [enable completion](docs/en/how-to/enable-completion.md) · [write a theme](docs/en/how-to/write-a-theme.md) · [move around a file](docs/en/how-to/navigate-code.md) · [ask about code](docs/en/how-to/ask-about-code.md) · [use a terminal](docs/en/how-to/use-a-terminal.md) · [configure a project](docs/en/how-to/configure-a-project.md) · [browse a project](docs/en/how-to/browse-a-project.md) · [use snippets](docs/en/how-to/use-snippets.md) · [run Node commands](docs/en/how-to/run-node-commands.md) · [talk to an agent](docs/en/how-to/talk-to-an-agent.md) · [make a release](docs/en/how-to/make-a-release.md) \|
89	\| Reference \| [command line](docs/en/reference/cli.md) · [keyboard](docs/en/reference/keyboard.md) · [menus](docs/en/reference/menus.md) · [theme format](docs/en/reference/themes.md) · [terminal windows](docs/en/reference/terminal.md) · [project settings](docs/en/reference/project-settings.md) · [project tree](docs/en/reference/project-tree.md) · [languages](docs/en/reference/languages.md) · [snippets](docs/en/reference/snippets.md) · [JavaScript tools](docs/en/reference/javascript-tools.md) · [agents and ACP](docs/en/reference/acp.md) · [the version number](docs/en/reference/versioning.md) \|
90	\| Explanation \| [architecture](docs/en/explanation/architecture.md) · [design decisions](docs/en/explanation/design-decisions.md) · [colouring and completion](docs/en/explanation/colouring-and-completion.md) · [terminal windows](docs/en/explanation/terminal-windows.md) · [project settings](docs/en/explanation/project-settings.md) · [project tree](docs/en/explanation/project-tree.md) · [snippets](docs/en/explanation/snippets.md) · [JavaScript tools](docs/en/explanation/javascript-tools.md) · [agent windows](docs/en/explanation/agent-windows.md) \|
91
92	The library's packages each carry their own `README.md` beside the code, in [turbo-core](https://rickub.com/turbo-editors/turbo-core).
93
94	## Where the code is
95
96	\| \| \|
97	\| --- \| --- \|
98	\| `main.go` \| flags, the terminal, the wiring \|
99	\| `internal/jslang` \| the profile, the JavaScript and JSON scanners, the four starter files \|
100	\| `demos/` \| a small Node project to open in the editor \|
101	\| everything else \| [turbo-core](https://rickub.com/turbo-editors/turbo-core) \|
102
103	The dependency graph is drawn in [`docs/diagrams/packages.drawio`](docs/diagrams/packages.drawio), checked against `go list`.
104
105	## Design in one line
106
107	Two dependencies — `tcell/v2` and `BurntSushi/toml` — and everything else from the standard library, including the Language Server Protocol client. Both come through turbo-core; this repository adds none of its own. The [design decisions](docs/en/explanation/design-decisions.md) page explains why.
108
109	## Requirements
110
111	Go 1.26 or later to build it — the editor is written in Go even though it is an editor for JavaScript. A terminal with mouse reporting, which is all of them. Node and npm for the JavaScript menu; `typescript-language-server` with `typescript@6` for completion. All three are optional.
112
113	## Licence
114
115	The other editors in the family are MIT-licensed; this repository's licence file is the owner's to add.