Lesson 13.213.2 The workbench

In everyday life. A carpenter's bench holds more than a saw. It has a square to check the angles, a level to check that a shelf is not tilted, and a tape measure. None of them cuts wood. They catch mistakes before the piece leaves the shop.

What you will learn. How to set up the tools once, what each reading machine checks, why they run in their strictest setting, and what the git commands the agent runs do.

Why it matters. The tools catch small slips in seconds, before you read any code. Only your reading catches a wrong rule.

A coding workbench is the same. Code lives in files. A command runs a file or a tool in a terminal, the window where commands are typed. In this book the agent types the commands. You read each one, and approve it, before it runs. Around the code sit tools that check it before you read it. One of them checks each value's type, the kind of value it is, such as text or a number. Code can carry a type label, such as : number after a name, which says what kind of value that name holds.

How do I set up the workbench?

Once, on your computer. You need three programs, each from its own official page:

• Git, the save points from Chapter 12: git-scm.com/downloads.
• Node.js, which runs TypeScript files: nodejs.org/en/download. Choose the LTS version, the long-term support release. This chapter needs version 24 or later.
• uv, the Python project tool: docs.astral.sh/uv. It also installs Python the first time a project needs it, if your computer does not have it yet.

TypeScript needs nothing more. Node 24 runs .ts files directly, and the type checker is a package that each project adds. The agent installs it, with your approval.

You may already have them, so ask first. Open your coding agent in any folder, and send:

Can you check whether Git, Node.js and uv are installed on this computer, and which versions? I need Node.js 24 or later. Please don't install anything yet. For anything missing or too old, tell me the official way to install it here, and wait for my yes before you run any install command.

Git also needs your name and email for each project. If the agent wants to set them for the whole computer, say no, and ask it to set them for this project only, as in Lab 12.

What reads the code before I do?

Four tools, and each is like something you already use.

• The runner runs a file: node src/list-vendors.ts, or uv run python -m brightline_ap.list_vendors for Python. It is like pressing Print. You see what the program does, right or wrong, only when it runs.
• Tests are small programs that run your code with inputs whose answers you already know, and compare. They are like an answer key: each one asks the code a question you can mark right or wrong. They run in seconds, every time.
• The type checker reads the code and checks that each value is used as the kind of value its label says. It is like a proofreader who checks that each name in a contract is used the way the contract defines it. It does not check whether the deal is a good one. It works before the program runs at all.
• The linter reads the code for style problems and common small slips, such as an import, a line that brings in other code, that nobody uses. It is like a spell checker: it flags slips, not wrong ideas. The lab's linter for Python is ruff, in npm run check:py.

Tests, the type checker and the linter are reading machines. They never get tired. The type checker and the linter read every line, and the tests run the lines they use. They do not replace your reading. They tell you where to look first. A valid line with the wrong rule, such as a sort that compares amounts as text, as in 13.6, can pass all three.

Why does Node run a type mistake?

Node runs TypeScript, but does not check it. It is like a printer that prints whatever you send: it does not proofread. Brightline's scripts are TypeScript files that Node runs directly. Node removes the type labels and runs the rest. So a type mistake can run, and print nonsense, until a type checker reads the file. That is why Lab 13 adds one: npm run typecheck. Python works the same way. Python ignores type labels when it runs. Pyright, a type checker, reads them.

At work. The agent changes Brightline's vendor script and says it is done. Before Ana opens the code, she asks the agent to run four commands, npm test, npm run typecheck, npm run test:py and npm run check:py, and reads what each prints. The type check fails on one line. The agent had stored an amount from the file in a variable labeled as a number, but the value was still text. The tests had passed, because no test used that line. The type checker read it anyway.

In TypeScript. Predict: will this run? Will the type checker accept it?

const fromFile: string = "482500";
const cents: number = fromFile;
console.log(cents + 61875);

$ node src/workbench.ts
48250061875
$ npm run typecheck
src/workbench.ts(2,7): error TS2322: Type 'string' is not assignable to type 'number'.

Node ran it and printed a wrong number, because + joined the text "482500" and 61875 into one piece of text. The type checker stopped at line 2, column 7, before anything ran. Its message means that text cannot go into a name labeled as a number.

In Python. Here str labels text and int a whole number.

from_file: str = "482500"
cents: int = from_file
print(cents + 61875)

$ uv run python brightline_ap/workbench.py
Traceback (most recent call last):
  ...
TypeError: can only concatenate str (not "int") to str
$ uv run pyright
workbench.py:2:14 - error: Type "Literal['482500']" is not assignable to declared type "int"

Python stopped at line 3 with a TypeError, because it will not join text and a number. Pyright found the wrong label on line 2 before anything ran.

Where the languages differ. When the label is wrong, TypeScript run by Node can keep running and print nonsense. Python ignores the label too, and stops only when a line does something the value cannot do, as line 3 of the Python example does. Both type checkers catch it before anything runs. That is the point of running them on every change.

Why strict mode?

So that missing labels count too. A type checker can only check the labels that are there, and in its default mode Pyright accepts code with no labels at all. An agent can write code like that. So both type checkers in this book run in strict mode, which reports a missing label as an error. It is like a proofreader who also refuses any name the contract never defines. 13.5 shows it on real code.

Which git commands do I need?

You need to know what each one does, so you can read it when the agent runs it. The first six are the git commands that mattered most in Chapter 12, from seeing what changed to giving a commit a tag. This chapter adds two. One is git init -b main, because the lab's folder comes with no history. The other shows how the tests changed since one commit.

The operating rule: have the agent run the tests, the type checker in strict mode and the linter on every change, read what they print before you read the code, and start reading where they point.

Figure 13.2. One change through the workbench. The reading machines go first because they are fast and never get tired. Your read of the diff comes before the commit, never after.

Practice it. Practice: the workbench, in your own tool, ten minutes.