@thedevlabs-io/labd 0.3.1 → 0.5.0

package/AGENTS.md

@@ -35,7 +35,7 @@ executes tools.
 
 ```
 packages/core/   the agent loop, tools, permission checks, sessions, checkpoints
-packages/tui/    terminal rendering - differential redraw, markdown, cards
+packages/tui/    terminal rendering - the full screen, differential redraw, markdown, cards
 packages/cli/    the binary: config, auth, extensions, and the four run modes
 vendor/labd/     submodule - the labd repo, for @labd/protocol
 test/            vitest; `e2e.test.ts` runs the built binary against a fake server
@@ -176,34 +176,70 @@ Do not "simplify" this into a list. The list version cannot do any of the three.
 
 ## Terminal rules
 
+Two kinds of program live in this repo, and the rules differ by which one you are in.
+
+**The interactive session owns the screen.** `labd` on its own runs
+`modes/screen.ts`: the alternate screen buffer, a scrollable transcript, a
+multi-line composer, popups for `/` and `@`, dialogs for lists, approvals inline.
+This replaced the "print into the scrollback, keep one live box at the bottom"
+model in 0.4.0. That model was principled - the terminal owned the transcript, so
+search and copy came free - and learners did not want it: they wanted an app, not
+a log. `--plain` still runs the old loop for one release and is deprecated. Rules
+for the screen:
+
+- **Full-screen only when stdin AND stdout are TTYs.** Anything else falls
+  through to the printing modes below; a learner must never type blind.
+- **Give the terminal back, whatever happens.** `Screen.leave` runs from the
+  normal exit, the `finally`, the signal handlers and the process `exit` hook, in
+  the reverse order of `enter`, and is idempotent. Raw mode or the alternate
+  screen left on looks like a broken machine.
+- **Frames are whole and drawn differentially with absolute positions.** No
+  relative cursor moves: there is no scrollback to keep in step with.
+- **Pure logic is separate from I/O.** `keys`, `layout`, `transcript`, `editor`,
+  `popup`, `dialog` know nothing about a stream and are tested without one.
+  `Screen` owns the terminal; `modes/screen.ts` is the state machine between them.
+- **The mouse is taken by default, for wheel scrolling, and `--no-mouse` gives
+  it back** - native text selection needs the terminal to have it.
+
+**The non-interactive modes own nothing and print.** `labd -p`, `--json`,
+`--mode rpc`, and anything with a piped stdout use `Renderer` and plain writes:
+
 - **Never assume a TTY.** Piped, redirected, or in CI, colour is off and the live
   region is a no-op. Escape codes in a log file are worse than plain text.
 - **The scrollback is not ours.** Finished output is printed and belongs to the
-  terminal; only the status line is a live region. That is what keeps search,
-  selection, and copy-paste working.
+  terminal; only the status line is a live region.
 - **stdout is the answer. Everything else is stderr.** A pipeline must receive
-  only what labd meant as the answer.
+  only what labd meant as the answer. The interactive session keeps this for
+  what it prints on the way out - the "session saved" line goes to stderr.
+
+**Everywhere:**
+
 - **Escape sequences are written as `\u001b` escapes**, never as literal bytes, so
   source files stay greppable ASCII.
+- **Zero runtime dependencies.** No ink, no blessed, no opentui: the TUI is the
+  repo's own `Screen` and differential drawing, so the bundle stays one file and
+  still works as a Node single-executable.
 
 ## Distribution
 
-Three artefacts, one source:
+**The GitHub organisation is private, and public docs must not link to it.**
+Learners cannot reach `github.com/thedevlabs-io/*`, raw.githubusercontent.com,
+or GitHub Release assets. The public channels are npm (`@thedevlabs-io/labd`, bin
+`labd`) and the VS Code Marketplace (`thedevlabs-io.labd`); README.md and every
+user-facing string point at those and nowhere else. This file is for
+contributors with access, so it may name the repositories.
+
+Two bundles, one source, one channel:
 
 - **`dist/labd.js`** - ESM, zero runtime dependencies, what npm's `bin` points at.
-- **`dist/labd.cjs`** - the same code as CommonJS. It exists because Node's
-  single-executable support runs its entry as CJS and refuses an ESM one outright.
-  This is why `bin/labd.ts` must never use top-level await.
-- **`dist/bin/labd-<os>-<arch>`** - a standalone executable, built by injecting the
-  CJS bundle into a copy of the `node` binary. Not cross-compilable, so the release
-  workflow builds one per runner. ~115 MB, ~40 MB compressed: the honest price of
-  "works on a machine with nothing installed".
-
-macOS needs the signing dance in `build-binaries.mjs`, and it is not optional -
-injecting invalidates the signature, and macOS kills an invalidly-signed binary
-rather than running it. The build also RUNS the binary before calling it done,
-because every one of those steps fails by producing something that does not start
-rather than by erroring.
+  `npm install -g @thedevlabs-io/labd` is the install; `npm update -g` the upgrade.
+- **`dist/labd.cjs`** - the same code as CommonJS. Kept because Node's
+  single-executable support runs its entry as CJS and refuses an ESM one, so a
+  standalone build stays possible without a code change. This is why `bin/labd.ts`
+  must never use top-level await; CI runs the CJS bundle to prove it loads.
+
+Standalone binaries, the install scripts and the GitHub Release step were removed
+in 0.4.0: they were only reachable through GitHub, which learners cannot see.
 
 `npm install -g git+ssh://...` cannot work: `dist/` is not committed and npm does
 not fetch submodules for a git dependency. `scripts/prepare.mjs` says so rather

package/README.md

@@ -3,80 +3,49 @@
 labd in your terminal — the Dev Labs assistant, in the project you're standing in.
 
 ```
-$ labd
-[o_o] labd in labd-cli on develop
-  labd changes files on its own - every answer can be put back in one go - and still asks before running a command.
-
-> why is session.test.ts failing?
-
-  ● Read   test/session.test.ts
-  ? Run a command
-    to see which of the eleven cases fails
-
-    npx vitest run test/session.test.ts
-
-    On auto, commands still ask - a command can do anything your shell can, and put back isn't one of them.
-    run this command? [y/N]
+ [o_o] labd  ·  labd-cli  develop  ·  session 3f9a12c0                          auto
+ ─────────────────────────────────────────────────────────────────────────────────
+ > why is session.test.ts failing?
+
+   ● Read   test/session.test.ts
+   ? Run a command
+     to see which of the eleven cases fails
+
+     npx vitest run test/session.test.ts
+
+     On auto, commands still ask - a command can do anything your shell can, and
+     put back isn't one of them.
+     y to allow  ·  n or esc to decline
+ ╭───────────────────────────────────────────────────────────────────────────────╮
+ │ > ask labd something  -  / for commands  -  @ to tag a file                   │
+ ╰───────────────────────────────────────────────────────────────────────────────╯
+  y allow · n decline · ctrl+c stop                              context 12% · credits 82%
 ```
 
-This is the same assistant as the [VS Code extension](https://github.com/thedevlabs-io/labd)
-and the one docked in the learning portal — same server, same prompt, same memory,
-same permission model. Ask something in your editor, follow up in your terminal.
+This is the same assistant as the labd VS Code extension (Marketplace:
+`thedevlabs-io.labd`) and the one docked in the learning portal at
+[learn.thedevlabs.io](https://learn.thedevlabs.io) — same server, same prompt,
+same memory, same permission model. Ask something in your editor, follow up in
+your terminal.
 
 ## Install
 
-**macOS / Linux** — a standalone executable. Nothing else needs to be installed:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/thedevlabs-io/labd-cli/production/install.sh | sh
-```
-
-**Windows** — same, in PowerShell:
-
-```powershell
-irm https://raw.githubusercontent.com/thedevlabs-io/labd-cli/production/install.ps1 | iex
-```
-
-**With npm**, if you already have Node 22+:
+You need Node 22 or newer. Then:
 
 ```bash
 npm install -g @thedevlabs-io/labd
-```
-
-Then connect:
-
-```bash
 labd login                      # approve a short code in your browser
 ```
 
-<details>
-<summary>Other ways, and what each is for</summary>
-
-| how | when |
-|---|---|
-| `install.sh` / `install.ps1` | a machine with nothing on it. Downloads a ~40 MB archive containing a single executable with the Node runtime inside it. |
-| `npm install -g @thedevlabs-io/labd` | you have Node. Smaller download, and `npm update -g @thedevlabs-io/labd` upgrades it. |
-| `npm pack` → share the `.tgz` | an air-gapped machine, or pinning an exact build. `npm install -g thedevlabs-io-labd-0.3.1.tgz`. |
-| copy `dist/labd.js` | you built from source. It has **zero runtime dependencies**, so that one file plus Node 22+ is a working install anywhere. |
-| clone + `npm link` | working on labd itself. |
-
-`npm install -g git+ssh://…` does **not** work, and says so rather than half-installing: `dist/` is not committed, and npm does not fetch the git submodule that the build needs.
-
-While this repository is private, the install scripts need a credential to read release assets. They use the GitHub CLI when it is signed in, or `GH_TOKEN` if you set one, and explain that rather than failing with a 404.
-
-**Building from source:**
+To upgrade:
 
 ```bash
-git clone git@github.com:thedevlabs-io/labd-cli.git
-cd labd-cli
-git submodule update --init     # the protocol lives in the labd repo
-npm install
-npm run build                   # dist/labd.js  (and dist/labd.cjs, for binaries)
-npm link                        # puts `labd` on your PATH
-npm run build:binary            # optional: a standalone executable for this platform
+npm update -g @thedevlabs-io/labd
 ```
 
-</details>
+The package is one bundled file with zero runtime dependencies, so that is the
+whole install. There are no standalone binaries and no `curl | sh` installer: npm
+is the one public channel.
 
 ## Using it
 
@@ -101,14 +70,52 @@ labd -c                         # pick up the most recent session here
 | `-e`, `--extension <path>` | load an extension file (repeatable; `/reload` keeps it) |
 | `--no-extensions` | load none, now and on `/reload` |
 | `--no-color` / `--color` | force colour off or on |
+| `--no-mouse` | leave the mouse to the terminal, for native text selection |
+| `--plain` | the older print-style session (deprecated; removed in 0.5) |
 | `-v`, `--version` | |
 
 Subcommands: `login`, `logout` (revokes the token server-side too), `sessions`
 (earlier sessions here), `trust` (let this project load its own extensions and
 name its own server).
 
-Inside a session: `@path` tags a file into your question, Tab completes both those
-and `/commands`, ctrl-c stops an answer without leaving.
+### Inside a session
+
+`labd` on its own opens a full-screen session: a header, a scrollable transcript,
+a box to type in at the bottom, and a footer with the keys that apply right now
+and how full the conversation is. The transcript follows the answer as it
+streams; scroll up and it stops following and tells you how many lines have
+arrived since (`End`, or scrolling back to the bottom, follows again).
+
+| key | |
+|---|---|
+| `enter` | send |
+| `shift+enter`, `ctrl+j`, or a line ending in `\` | new line in the box (it grows to 8 rows) |
+| `/` | a list of commands appears above the box; `↑↓` moves, `tab`/`enter` accepts, `esc` closes |
+| `@` | the same, for files in the project — `@src/index.ts` tags the file into the question |
+| `tab` | complete the command or path being typed |
+| `pgup` / `pgdn`, mouse wheel | scroll the transcript |
+| `home` / `end` | top / bottom of the transcript (with an empty box; otherwise they move within the line) |
+| `↑` / `↓` | earlier questions, when the caret is on the first / last line |
+| `esc` | close a list or dialog; otherwise jump back to the bottom |
+| `y` / `n` | answer an approval card. Nothing else answers it, and `enter` never does |
+| `ctrl+c` | stop the answer; else clear the box; else press it again within 2 s to quit |
+| `ctrl+d` | quit |
+| `ctrl+n`, `ctrl+o` | new session, earlier sessions |
+| `ctrl+l` | redraw |
+
+`/help`, `/sessions` and `/tree` open a dialog you can type into to narrow the
+list; `enter` picks — a session to resume, or a point in this session to continue
+from. Approvals are never dialogs: the card is drawn inline in the transcript
+with its context, and `y` is the only key that allows it.
+
+Two flags for the screen. `--no-mouse` leaves the mouse to the terminal (the
+session takes it for wheel scrolling, and native text selection needs it
+released); `mouse: false` in a settings file does the same. `--plain` runs the
+older print-style session, where answers land in the terminal's scrollback and
+only the box is redrawn — kept for one release for terminals that cannot cope
+with the alternate screen, and deprecated. `sidebar: true`, or `/sidebar`, adds
+a panel with the project, branch, mode and recent steps when there are 120 or
+more columns.
 
 | command | |
 |---|---|
@@ -118,7 +125,9 @@ and `/commands`, ctrl-c stops an answer without leaving.
 | `/redo` | reapply what `/undo` put back |
 | `/tree` | every point in this session; branch from any of them |
 | `/resume <id>` | continue from a point in `/tree` |
-| `/sessions`, `/session` | earlier sessions here; where this one is stored |
+| `/sessions`, `/session` | earlier sessions here (a dialog; `enter` resumes); where this one is stored |
+| `/new` | start a fresh session; the current one stays saved |
+| `/sidebar`, `/clear` | show or hide the side panel; clear the screen |
 | `/usage` | what's left of this month's allowance |
 | `/trust` | let this project load its own extensions |
 | `/reload` | reload extensions and the file list |
@@ -173,9 +182,10 @@ Two more rules worth knowing before you point this at a repository you didn't wr
 | `.labd/extensions/` | per-project extensions, loaded once trusted |
 
 `settings.json` keys, global or per project: `timeout` as `commandTimeoutSeconds`
-(5–600), `effort` (`low`/`medium`/`high`), `checkpoints` (`true` by default), and
-`serverUrl` — honoured from a project file only once that project is trusted.
-`mode` is read from the global file only.
+(5–600), `effort` (`low`/`medium`/`high`), `checkpoints` (`true` by default),
+`mouse` (`true`; the full-screen session takes the mouse for scrolling), `sidebar`
+(`false`), and `serverUrl` — honoured from a project file only once that project
+is trusted. `mode` is read from the global file only.
 
 `LABD_HOME`, `LABD_SERVER_URL`, and `LABD_TOKEN` override the corresponding thing;
 the last is how you run labd in CI without pairing. `NO_COLOR` turns colour off,
@@ -256,7 +266,7 @@ in `~/.labd/extensions`.
 ## Development
 
 ```bash
-npm run build      # bundle to dist/labd.js
+npm run build      # bundle to dist/labd.js (and dist/labd.cjs)
 npm test           # vitest (build first — the e2e suite spawns the binary)
 npm run check      # typecheck + tests
 ```