9 posts tagged with "Tooling"

Every codebase has the same quiet failure mode. A paragraph of reasoning is written next to the code it explains — why a retry creates a new job instead of re-applying the failed one, why a cache keys on identity rather than on a version — and then the code moves. Six months later the paragraph is either wrong, or deleted by somebody who read it as noise.

The writing is rarely the problem. The storage is. The argument was copied into the one place that cannot maintain it, and a copy has no owner and no seat in any review.

Split the claim from the argument instead. The comment keeps the claim — the conclusion a reader needs at that point in the code — and points at where the argument lives: a decision record, a design note, an architecture decision record, an issue that is really kept. That is all a prose cross reference is. An address, not a copy.

// A retry creates a new job instead of deleting the failed one @@D-42

A friction entry is written in the words of the problem, and it is read months later by somebody recalling a situation rather than a phrase. The two rarely match. F-325 is titled A cached stats read made a finished ingest look stuck; the question that should find it sounds more like "the summary endpoint kept reporting work as outstanding after the log said it was done". What the entry and the question share is the situation, and a text search cannot see it.

The previous post was about the notes themselves — markdown, ids, one command that owns their format. This one is about what now sits beside them: an index the same command feeds as it writes, and a search that takes a question in your own words.

Every team discovers the same thing about its own bug tracker: the useful knowledge is not in the ticket, it is in the comment where somebody says what they tried, why it did not work, and what they did instead. That comment is usually the last thing written and the first thing lost, and the next person pays for the same afternoon all over again.

This repository keeps that kind of note in the repository, in markdown, under three headings — frictions, todos and decisions — written through a command that owns their format. It is deliberately not a tracker. It is the smallest thing that makes a note citable, greppable and verifiable, and it exists because a coding agent's session starts with no memory at all.

Every framework with a strong convention ends up documenting that convention twice. Once as prose — "a handler file is named subjectObjectPredicate, it exports the same name, it forwards $meta" — and once as the skeleton somebody pastes from the last file they wrote. The prose drifts from the code, the skeleton drifts from the prose, and the person following either one finds out which by compiling.

Blong moved the skeletons into the framework. There is now an API that writes a primitive on request, validates the name before anything reaches disk, and can tell you what is already wired up in the process you are talking to. It is called kukum, and it is the answer to a question the skills used to answer in prose.

Count the backends a normal system depends on. A relational database for the data, a bucket for the files, a key-value store for the cache, a queue for the events, a secret store for the credentials, a directory for the users, and a cluster running all of it. Then count the screens: one per backend, each with a slightly different table, a slightly different filter box and the same four bugs.

The commander realm describes each of those as a source — a namespace of triples with levels — and renders all of them with one explorer. The screens disappear; what remains is a descriptor per backend and, where the connection needs one, a small adapter.

Every codebase accumulates a directory of shell scripts, and every one of them starts as a good idea. load-db.sh because the connection string was long. read-log.sh because the logs only existed in a terminal that had already been closed. open-trace.sh because a Playwright trace is a zip of JSON lines and reading it by hand is a tax on every failure. Each script is correct on the machine of the person who wrote it, and none of them is documented anywhere a new contributor would look.

Blong puts that directory in one command, and the reason it is worth a post is not the count of subcommands — it is that the commands are shared by the two kinds of caller this repository has: a person at a terminal, and a coding agent working through the same loop.

blong-dev lint [files...]    Run tsc + cspell + eslint in current package
blong-dev lint-staged        Lint git staged files across all affected packages
blong-dev test               Run tap tests in current package
blong-dev report vitest      Convert coverage/vitest.json into .ci-report/
blong-dev ci-report          Aggregate .ci-report/ into the CI report
blong-dev playwright [args]  Run Playwright tests in current package
blong-dev proxy [opts]       MLE proxy for curl (--port/--target/--username/--password)
blong-dev trace <trace.zip>  Print a human-readable Playwright trace timeline
blong-dev log [ulid] [opts]  Fetch log entries from cacache (--output/--level/--search/...)
blong-dev sql [opts]         Run a SQL query via .blong_devrc (--output json|pretty)
blong-dev memory <verb>      Add, list, show, close, format or check agent memory entries
blong-dev docs <verb>        List, generate, check or verify the docs site artefacts

A template engine is a small feature with a large security surface. The moment the text being rendered is not yours — a tenant's notification, a partner's message, a row somebody edited in an admin screen — the template is untrusted code, and "render this string with these variables" is a sentence that has ended more than one product.

The interesting part of Blong's template engine is not that it renders ${name}. It is that the API has two modes, and the choice between them is a statement about where the template came from.

There is a specific kind of support request that every deployed system generates: something is wrong in a running environment, the fix is one file, and the file is on a server you are not supposed to log into. So you describe the file to a colleague who has access, they describe it back, and eventually someone edits it over a shell with three terminal windows open and no way to see the diff.

The last post in this arc is about removing that trip. The framework can serve a folder over HTTP, and a VS Code extension implements a filesystem on top of it — the explorer opens the running realm's tree, the file is edited where it lives, and a command runs on the server with its output streamed back.

Enterprise Integration Patterns are usually a framework you adopt: you import a DSL, declare routes in its vocabulary, and your business code learns to speak that vocabulary. It works, but the routing decision now lives in a language the rest of the codebase does not use, and replacing one destination with a test double means understanding the framework's lifecycle.

In Blong a pattern is not a framework — it is a handler. One file, a few lines, calling other handlers by name through the proxy. The pattern shows up as the shape of the function, not as a dependency.