Itay Wolfish

Testless against hono: the receipts

Sat, 25 Jul 2026 00:00:00 GMT

The last testless post ended on a hedge: the tool works, over-approximation is the cost. That’s a comfortable thing to say about your own fixtures, where every edge case is one you wrote on purpose. It’s a different claim on a codebase you don’t control, with a history you didn’t curate and a call graph nobody built to be readable. So I pointed testless at one and wrote down what happened, including the part that made me wince.

The setup

I picked honojs/hono, a real, actively maintained web framework with 2,703 tests across 384 files, cloned shallow at a recent commit. Not a toy repo, not one I’ve touched, not tuned in any way for testless to look good on. I indexed it, then walked back through the last fifty commits looking for ones that touch exactly one non-test source file with a small, single-function fix: no version bumps, no test-only commits, no docs or CI chore commits. Three qualified on the first pass, so I used all three instead of discarding the inconvenient one.

For each commit, the loop was the same:

git checkout <commit>~1
testless index
testless changes --from <commit>~1
testless select --from <commit>~1

changes prints the seeds testless found in the diff: the changed function, plus any new test cases. select walks the call graph from those seeds and prints the tests that could observe the change, ready to hand to a runner with --format args.

Two clean hits, one that isn’t

Here’s what came back:

Commit (changed function)	Selected / total	% of suite	Distinct test files
method-override fix (`methodOverride`)	12 / 2684	0.45%	1
cache fix (`cache`)	39 / 2681	1.45%	1
client/utils fix (`replaceUrlParam`)	1271 / 2683	47.4%	35

The first two are what you’d want from a tool with this pitch: a one-function fix to a middleware selects the tests in that middleware’s own test file and nothing else. Both landed in under 150ms, including the diff walk. The selected sets weren’t just numerically small either; I checked, and they visibly contain the test that actually exercises the changed function, plus its neighbors in the same file.

The third one is the outlier, and it gets equal billing here, not a footnote. replaceUrlParam is a low-level URL helper used by hono’s RPC client, which gets imported, directly or transitively, by dozens of runtime-tests/* files that spin up app.fetch across bun, deno, node, and workerd. That’s a real fan-out, not noise: I checked those selected tests too, and they do call code that runs through the changed function. But 35 files and 1271 tests for a one-function diff is still a lot of blast radius, and it’s worth being honest about why.

Why the 47% happens

testless stats on this repo reports roughly 40% of call edges unresolved, meaning testless can see a call site but can’t pin it to a specific definition. That’s what you get from dynamic dispatch, re-exports, and the kind of indirection a framework’s client code tends to accumulate. The guarantee from the last post still holds: when testless can’t resolve an edge, it doesn’t drop it and hope. It widens by name across the whole codebase instead, because a missed test is the one failure mode the design won’t allow.

That guarantee is exactly why the 47% happened. Widening by name is conservative by construction, and conservative means it can’t tell the difference between “this callback is genuinely reachable from forty files” and “this callback shares a name with forty unrelated things.” Right now it can’t tell those apart, so it assumes the worse one. The fix isn’t a different guarantee, it’s better resolution: SCIP-sharpened type information in place of name-based widening, which is next on the list, specifically because this benchmark is the number that justifies building it.

The other kind of fast

The other number worth writing down is what caching does to index itself. Cold, on a fresh clone with no cache, indexing 384 files took 2011ms of internal parse time. Warm, immediately after, with every file reused from cache: 53ms. That’s roughly 38x on the number that matters, and about 12x on wall time once you count process startup:

$ time testless index
indexed 384 files (384 parsed, 0 reused) in 2011ms
testless index  1.83s user 0.21s system 98% cpu 2.070 total

$ time testless index
indexed 384 files (0 parsed, 384 reused) in 53ms
testless index  0.05s user 0.11s system 95% cpu 0.165 total

select itself doesn’t show that gap. I edited a single function body and ran select cold, then warm, immediately after: 103ms versus 98ms, statistically indistinguishable. select only has to reparse the one changed file no matter what state the cache was in, so a fixed per-invocation overhead of roughly 90 to 100ms (process startup, the git diff) dominates the actual incremental-parse work. The caching win is on full re-index of a repository, not on the single-file select you’d run in CI on every commit.

What I won’t claim

Three commits is a sample, not a rate. I’m not going to tell you testless falls back to run_all 0% of the time on real repos because it did so zero times out of three tries; that’s a fact about three commits, not a distribution. The honest version is narrower: for isolated, single-function diffs at this codebase’s size, every attempt produced a real selection instead of giving up and running everything.

What this changes about CI math

Here’s the part that still holds even with the 47% sitting right there in the table: two of the three real fixes I tested selected 12 and 39 tests out of roughly 2,700, each under 1.5% of the suite, in under 150ms. Those aren’t cherry-picked; they’re two-thirds of every commit I tried. The third one ran half the suite, which is worse than I’d like and exactly as bad as an unresolved call graph makes it. Even averaged in, a tool that turns “rerun everything” into “rerun 1% of it” most of the time, and “rerun half of it” the rest, is still a CI bill that looks nothing like the one you’re paying today.

adeptability learns to publish, automate, and admit what it drops

Thu, 23 Jul 2026 00:00:00 GMT

Since the last post, adeptability kept growing. Echo used it to consume shared skills. A month later we also publish them, automate around them, and trust it when a harness drops a file. Four threads carried that: publishable libraries, agents that compose into loops, honest rendering, and a scope split that keeps two things from sharing one directory.

Publishing a library, not only pulling one

The first post described consuming a library: commit a {name, remote, ref} reference, and adept resolves it into a per-machine store. It never covered who publishes that remote, which until 1.4 meant a hand-rolled repo with no template.

adept init --as-library scaffolds a repo meant to be that remote, with bundled library-management skills for the first contributor. A separate bug had status lumping private skills into library-skill counts, hiding the drift you need to spot; 1.4.1 fixed it. adept library update added a workflow: fetch every library, show what changed, ask before applying.

adept library update                # check every library, prompt before applying
adept library update org-std --yes  # apply without prompting

Publishing a library was possible by hand. Now it is a command, not a README nobody reads.

Scaffolding agents instead of hand-writing them

The library already carried one hand-written PR-reviewer subagent. Scaling past it meant a template, and 1.7 shipped it.

adept agent add pr-reviewer --template evaluator scaffolds a canonical subagent that renders into .claude/agents/, Cursor’s agents, Codex’s .toml format, and the rest: the same author-once model as skills. adept agent check runs a safety scan and a best-practice lint before you trust it with anything.

Loops got the same treatment: a discovery skill decides what to look at, an evaluator agent that can say no, and a schedule triggers the round. adept loop add stale-prs --workflow --edit scaffolds all three at once, plus a GitHub Actions cron skeleton for unattended runs. It also prints a first-loop checklist: state file, isolation, token cap, human review. A loop with no evaluator and no cap is not automation. It is an unsupervised script with better branding.

When a harness drops a file without saying so

Codex’s and Copilot’s renderers computed warnings when a skill’s sidecar files, scripts/ or references/, could not survive that harness’s format. Nobody read them: the warnings got built, then discarded before adept sync printed anything. A skill with a scripts/ directory rendered clean into Claude Code and silently lost the script in Codex.

A 1.6 fix wired those warnings into the sync summary and the JSON output. Losing a sidecar a harness format cannot represent is sometimes unavoidable; losing it silently is a bug.

Getting the binary onto every machine, properly

go install covers Go developers, not everyone else. 1.7 added a Nix flake, so nix profile install github:itaywol/adeptability works without that detour. 1.8 added completions everywhere the binary ships: Nix, the goreleaser archives, the Homebrew formula. Cobra generated them at runtime; packaging installs them.

Then the release pipeline broke itself: cosign v3 defaults to the sigstore bundle format and refused to sign without --bundle, breaking the 1.8 release. The fix pins --use-signing-config=false --new-bundle-format=false, keeping the .sig/.pem outputs install.sh verifies. A dependency bump breaking the release signer made for a fun Saturday.

Proving it works instead of describing it

None of this shows up in a bullet list, so the README got a demo GIF: one canonical skill, adept sync, rendered into Claude Code, Cursor, Codex, and OpenCode in one recording. assets/demo.sh reproduces it exactly, built with asciinema piped through agg: a real session replayed on demand, not hand-edited marketing.

Two different things sharing one directory

This one had been there the whole time: skills lived in a per-machine store, but libraries lived there too. One project’s adept library update could yank a ref out from under a project counting on it to stay put.

1.9 splits the two. Libraries clone into .adeptability/libs/ inside the project by default, .adeptability/.gitignore kept in sync automatically, and adept migrate re-clones configured libraries from the machine store into the project. The machine store still exists for skills: --global on sync, status, and the rest of the CLI manages one skill set across every project. Agent subcommands, loop add, and hook install stay project-scope: a global agent or hook never made sense.

Current build is 1.9.0: install via go install, Homebrew, the curl installer, or the Nix flake, listed in the README. Docs cover every command; the project page has the design decisions, if the changelog is not enough.

I got tired of CI re-running tests nobody doubted

Thu, 23 Jul 2026 00:00:00 GMT

I have spent enough time inside a large monolith to know a specific kind of pain. Touch one utility function, and forty unrelated tests fire, because the build tooling treats the file that function lives in as the unit that matters, not the function itself. Multiply that across a monorepo where dozens of services share a test runner, and every small change reruns entire suites, burning CI minutes re-proving things nobody doubted. That is the complaint behind testless, a Rust CLI that reads a code change and outputs the exact tests it affects, down to the function, using static analysis instead of a test runner’s coverage data.

File-level selectors like jest --findRelatedTests, vitest --changed, and Nx’s affected narrow a run to changed files, which still reruns forty tests for a one-function edit. Runtime coverage tools such as Wallaby and Datadog’s Test Impact Analysis go finer, but they cost money and need an instrumented test process before they produce anything. Nothing free and local selected at function granularity from a plain diff. That gap is what testless set out to close.

One guarantee, no exceptions

The design still commits to one rule: the selected set always contains every test truly impacted by a change. It over-approximates, never under. When indexing hits a file it cannot parse, a corrupt cache, or any other internal error, the output is not a smaller selection: it is run_all, with a reason attached. That rule is what makes everything below trustworthy enough to wire into CI.

From graph to answer

testless select --from <rev> is the command that did not exist a day ago. It walks the graph from the changed defs and prints the impacted tests, each with the full describe/it or package/func chain that identifies it. Exit code 0 means a real selection came back; exit code 2 means testless fell back to run_all and says why. testless changes --from <rev> shows the step before that: the classified seeds, before the walk turns them into tests.

select --format args renders each selected test as a runner invocation instead of a bare name:

vitest run src/math.test.ts -t 'add > handles negatives'
go test ./calc -run '^TestAdd$/^negatives$'
cargo test walk::tests::widens_module_init -- --exact

Each line is ready to paste into a shell or hand to a runner directly, one format per language testless understands.

Here’s that loop recorded end to end, from the diff to the runner-ready output:

How a diff becomes a selection

Three pieces do the work. A structural differ fingerprints each def’s signature and body separately, ignoring formatting and comments, so a reformatted file selects zero tests instead of the whole suite. A classifier turns each surviving change into a seed: a body edit, a signature edit, a new def, or a changed module top level. A reverse-reachability walk starts at those seeds and follows caller, reader, and container edges back to every test that could observe them. Output comes out in deterministic sorted order, so two runs against the same diff produce the same list.

Module-level seeds widen further, on purpose: importing a module reruns its top-level code, so a change there spreads to every file that imports it, transitively. A test helper keeps propagating impact to whatever calls it, instead of stopping at the helper itself.

Rust joins, and the tool tests itself

Rust is now a third supported language, with its own resolver crate sitting next to the TypeScript and Go ones behind the same shared trait. CI now indexes and selects against testless’s own repository on every push. A cold index runs first, then a warm-cache reindex that should reparse nothing, then a selection run against the working tree that should come back empty on a clean checkout. If the tool cannot analyze itself correctly, nothing else it says can be trusted.

Shipped

testless is on crates.io at 0.5.0, with release-please cutting versions and prebuilt binaries for Linux and macOS, on both x86_64 and aarch64. cargo install testless gets a binary instead of a clone and a build. There’s also a small site at testless.itaywol.tools with the same pitch, for anyone who wants it without a terminal:

What over-approximation still costs

The design spec’s edge-case catalog sits at sixty-four entries now: thirty-two for TypeScript and JavaScript, eighteen for Go, fourteen that cut across languages. Each one gets a fixture and a snapshot of the expected selection. The plan is a ground-truth run on top of that: prove the selection is a superset of what a full before/after test run actually touched.

Over-approximation is a guarantee, not a compliment. An unresolved dynamic call widens by name across the whole codebase, so one untyped callback can drag in tests that have nothing to do with the change. There is still no why command to explain a selection, so a wider-than-expected run means reading code, not reading output. Go’s implicit interface satisfaction is not modeled yet, and SCIP-sharpened resolution, which would replace a lot of that name-based widening with real type information, is next. The tool works now. Making the over-approximation smaller is the rest of the job.

Cloning a repo runs code, and your hook manager is fine with that

Sat, 11 Jul 2026 00:00:00 GMT

Git hooks are code the repository author wrote that runs on your machine during ordinary git operations: commit, checkout, push. Most hook managers copy the cloned config and run it, so cloning becomes an implicit “execute arbitrary code” step you never explicitly agreed to. I built hookguard to close that hole without giving up the convenience that makes hooks worth using. This is the problem it solves and how the trust model works.

Two things nobody gives you together

Every hook manager forces a choice between automatic and safe, and I wanted both.

Automatic means a teammate clones the repo and the hooks are already wired up, with nothing to install by hand. That matters because the alternative is the oldest failure mode in the category: someone forgets to run the setup step, the pre-commit checks never fire for them, and the formatting job on CI catches what a local hook should have. husky gets automatic through an npm postinstall script, so it needs Node and a package.json. pre-commit needs Python, and it refused auto-install-on-clone outright. lefthook is a native Go binary, which I respect, but its trust model is the same as everyone else's: none.

Safe means nothing executes on my machine that I did not agree to run. Here is where every tool collapses the two decisions into one. Opting in, or cloning, becomes blanket permission for whatever commands the repo ships now and whatever it ships after the next git pull. “Hooks run automatically” and “you trust this repository” get treated as the same yes. I wanted them to be two.

Install is automatic, execution is gated

hookguard splits the decision. You run git hooks install once per machine, which sets git's init.templateDir so every future clone drops a shim into .git/hooks/. The shim does not run your commands. It execs git-hooks run <hook>, which is a gate.

That split looks like this:

The hooks themselves are committed to the repo in .githooks.toml:

[hooks]
pre-commit = [
  "cargo fmt --check",
  { run = "rustfmt --check {staged_files}", glob = "*.rs" },
  ".githooks/check.sh",
]

Each entry is a bare command run through sh -c, or a table that adds staged-file awareness. {staged_files} expands to the staged file list, and an optional glob filters it first, skipping the command when nothing matches. Any command may reference a script committed under .githooks/, and that script's content is covered by consent exactly like the toml.

Consent is keyed to content

The first time a hook would fire, the gate prompts on your terminal with the exact commands about to run, and executes nothing until you accept:

this repository wants to run the following hooks (.githooks.toml):

[pre-commit]
  cargo fmt --check
  cargo clippy -- -D warnings

these commands will run on your machine during git operations.
accept? [y/N]

Your answer lands in .git/config, which is never cloned, keyed to a hash of everything executable: git hash-object over .githooks.toml plus every file under .githooks/, walked in sorted order. Because consent is bound to content, there is no “trust once, run forever” window. An upstream that changes one byte of what its hooks do produces a different hash and prompts you again. The re-prompt shows a git diff of each changed file against what you accepted, not the whole config dumped at you.

Cloning, reviewing, and accepting all run together like this:

On a machine with no terminal, there is nothing to prompt on, so the answer is always no. CI, cron, and scripts get a safe-off no-op. For a pipeline that should run the hooks, GIT_HOOKS_CONSENT=accept:<hash> opts in only while the content still matches that hash. The moment the committed hooks change, the pin stops matching and the run falls back to skipping them, which is the direction you want CI to fail.

Signing kills prompt fatigue without reopening the hole

Content-keyed consent is sound and noisy. A maintainer who legitimately updates the hooks re-prompts every teammate, every time, and prompt fatigue trains people to hit y without reading. Signed trust removes the noise by moving what you trust from the content to a key.

A maintainer signs with git hooks sign --key ~/.ssh/id_ed25519, and verification runs ssh-keygen -Y verify pinned to the git-hooks signature namespace, so a signature made for some other purpose can never be replayed here. A cloner who runs git hooks trust <fingerprint>, repo-local or org-wide in ~/.config/git-hooks/policy.toml, gets silent auto-accept of future signed changes. An untrusted signature still prompts; an invalid one screams. You stop vouching for bytes and start vouching for a key, once.

What consent does not cover

hookguard's whole pitch is that it does not hand-wave the boundary, so here is the honest limit. Consent is a snapshot of specific bytes, not a sandbox.

Runtime-referenced repo files. An inline command can invoke any file in the working tree at run time: ./scripts/deploy.sh, make, a checked-in binary. Those files are not in the consent hash, so their contents can change without re-prompting. Put anything you want covered under .githooks/. The prompt warns when a command looks like it references a repo path outside .githooks/, but that heuristic has false negatives.
Programs on $PATH. Consent covers the text cargo clippy, not whatever cargo resolves to on your machine.
The network. A hook can download and run remote content. Consent covers the command that reaches out, never what comes back.
Everything after you accept. Accepted hooks run with your full user privileges. There is no sandbox behind the yes.

And signed trust concentrates that risk into one place: a compromised signing key is game over. Whoever holds it can sign arbitrary hooks that every trusting machine auto-accepts and runs. Trust is the boundary, so git hooks untrust is the revocation path the moment a key is suspect. I would rather say that plainly than pretend a signature is a sandbox.

Why Rust, and why one file

hookguard is around 1,320 lines of Rust in a single file, with the toml crate as its only dependency. That is deliberate. A tool whose entire value is “safe to recommend org-wide” has to be auditable in one sitting, and it has to install the same way on a laptop, in CI, and in a container without dragging a runtime along. The e2e suite is one 734-line file with no dev dependencies, isolating HOME per test and using setsid to drop the controlling terminal so the no-TTY path gets tested for real.

The project page has the design decisions, the repo has the code and a comparison table that is fair about where pre-commit and gabyx/Githooks beat it, and SECURITY.md is the full trust model. Install with cargo install hookguard, run git hooks install once, and cloning stops being a code-execution step you did not sign up for.

No backend, but a real database

Sat, 04 Jul 2026 00:00:00 GMT

I built Scrolls Buddy, a planning tool for a MapleStory private-server community. The audience is about twenty people a day. That number is the whole story of the architecture, because it made one decision for me before I wrote any code: there would be no backend.

Not “a small backend.” None. No server to secure, no database to operate, no bill that grows with traffic. The interesting engineering was refusing to give up any real capability to honour that, because “no backend” usually means “no persistence, no analytics, no data,” and I wanted all three.

Here is how each one survived the constraint.

Persistence: SQLite in the browser

The app has session history, saved item configurations, and scrolling outcomes I want to query: “show me this session’s profit,” “what did I roll last time.” That is relational data, and localStorage is a bad place to keep it the moment you want to ask it a question: it is a string key-value store, and you end up hand-rolling a query engine over JSON blobs.

So the app runs SQLite compiled to WebAssembly, persisted into the browser through IndexedDB. Real SQL, real tables, real queries: the database lives in the tab instead of on a host. The data never leaves the device, which means there is nothing to breach, nothing to migrate, and nothing to back up. For a single-user tool, the user’s own browser is a perfectly good place for their data to live.

External data: pulled, not hosted

Item names, icons, and base stats are not mine to own: they are game data with canonical public sources. Instead of scraping and hosting them, the app fetches from public game-data APIs on demand and lets Cloudflare’s edge cache the responses. No asset pipeline, no scraper to babysit, no copy of someone else’s data drifting out of date. The client stays thin over sources that are already authoritative.

Analytics: first-party, still serverless

The one thing people assume forces a backend is knowing whether anyone uses your thing. It does not. The app sends product events to PostHog, but through a first-party /ingest path on its own domain rather than straight to PostHog’s servers. That rewrite keeps the telemetry first-party and lets it survive ad blockers, while the actual event storage is PostHog’s problem, not mine. I run no analytics infrastructure and still get a real funnel: it is how I know the tool holds ~20 daily actives and which features earn their place.

What runs it

A static React/Vite bundle on Cloudflare Pages, deployed on push, on a subdomain of a domain I already manage. SQLite-WASM for the data layer, PostHog for the feed, public APIs for game data. It is a PWA, so once the data is cached it works offline, which follows naturally from the logic and storage already being local.

Total cost to keep running: zero. Total servers to operate: zero.

The point

The reflex, when you want persistence and analytics, is to reach for a backend. Most of the time you are reaching for it out of habit. Between WebAssembly builds of real databases, edge caching in front of public data, and analytics vendors that only need a beacon, a surprising amount of “backend” is a client-side concern wearing a server costume.

Scoping the tool to twenty people is what made this possible, and, honestly, what made it finished. The serverless architecture was not a clever trick bolted on afterward; it was the direct consequence of building the right size of thing for the actual need. The full write-up, including the MapleRoyals scrolling problem it solves, is on the project page.

Author once, run in every agent: how we share AI skills at Echo

Sat, 04 Jul 2026 00:00:00 GMT

At Echo we lean on AI coding agents hard, and we do not standardize on one. I use Claude Code, someone else lives in Cursor, another engineer runs Codex. That is deliberate: the same “engineers as product owners” instinct that shapes how we build also means people pick the tool that fits their head.

The problem is that a coding skill, how we run the tests, what the PR-review checklist is, which boring-stack conventions we hold to, is the same regardless of which agent you opened. But the moment you write it down, every harness wants it in its own format. Claude Code wants SKILL.md files under .claude/skills/. Cursor wants .mdc rules with its own frontmatter. Codex reads one aggregated AGENTS.md with a size budget. Write the convention three times, and within a week the three copies have drifted and nobody trusts any of them.

I built adeptability to kill that drift. This is how it works and how we actually use it.

The idea: skill as source, harness as build target

adept treats one canonical skill as the source of truth and every harness’s format as a build target: the same relationship your source code has to compiled artifacts.

You author once: a SKILL.md with YAML frontmatter and a markdown body, plus optional scripts/ and references/ sidecars. Then:

adept sync     # render the canonical skill into every enabled harness
adept status   # init state, libraries, harnesses, and drift at a glance

adept sync writes .claude/skills/run-tests/SKILL.md, .cursor/rules/run-tests.mdc, the right block in Codex’s AGENTS.md, and so on, each in that harness’s native format, with the frontmatter translation, activation rules, and size budgets handled per harness. Subagents work the same way: one canonical agent definition renders into .claude/agents/, Cursor’s agents, Codex’s, and the rest.

Edits happen inside harnesses, so sync goes both ways

The naive version of this tool is one-directional and breaks the first time someone tweaks a rule inside Cursor. adept handles it: a content-hash state machine classifies every rendered file as synced, ahead, behind, or diverged. Edit a skill inside a harness and adept sync-from pulls that edit back into the canonical source, then adept sync republishes it everywhere. There is no lockfile: drift is computed from hashes at read time, so there is no second artifact to keep honest.

How we share at Echo

Two layers, because we have two kinds of skills.

Org-wide conventions live in a versioned library. The stuff every repo should know (our code-as-liability conventions, the boring-stack choices, a shared PR-reviewer subagent that reviews to our standard) lives in a library with a remote and a ref. A project commits only the reference, not the content; adept materializes the skills into a per-machine store on demand. A teammate clones a repo, runs adept, and gets the same skills and the same reviewer agent rendered into whichever harness they use. Bump the library ref and everyone moves together.

Project-specific skills are committed in the repo. How this service runs its tests, builds, and deploys is not org-wide knowledge: it belongs to the repo. Those canonical skills sit in the project, and adept sync renders them locally. Clone, sync, and your agent already knows how to run the test suite and ship the thing, no matter which agent it is.

The payoff is concrete: a convention is written once and true everywhere. When we change how we review PRs, I edit one skill and bump the library. I am not chasing the same change through three formats and hoping the Cursor copy and the Codex copy agree.

Scheduled work, too

Some of what we want agents to do is not interactive. adept loop add composes a discovery skill, an evaluator agent, and a cron skeleton in one shot: a scheduled loop that goes looking for something and acts on it. It is the same author-once model applied to automation instead of an interactive session.

Why I think this is the right shape

Echo’s whole engineering bet is that code is a liability and the solution is the asset. Skills are the same. The convention, the judgment about how we work, is the asset worth keeping. Which harness’s file format it happens to be trapped in is pure liability, and duplicating it across three of them is liability times three. adept makes the skill the durable thing and the harness format disposable, which is exactly the right way round.

adeptability is a single static Go binary, installable via Homebrew, go install, Nix, or a curl script. The project page has the design decisions, the repo has the code, and the docs cover every command and a harness-by-harness breakdown of exactly what gets emitted where.

TypeScript unions and discriminating unions

Tue, 08 Dec 2020 00:00:00 GMT

A union type says a value is one of several shapes. That is exactly how application state works: a request is loading, or it failed, or it has data. So I reach for unions constantly. The catch is that a bare union only lets you touch the fields every member shares. This is how one literal field fixes that and makes the compiler narrow the type for you.

A union only exposes its shared fields

Model a user-loading state as three interfaces, then a union over them:

interface UserLoadFailed {
  statusCode: number;
  message: string;
}
interface UserLoading {
  statusCode: number;
  isLoading: boolean;
}
interface UserLoaded {
  statusCode: number;
  data: User;
}

type UserState = UserLoadFailed | UserLoading | UserLoaded;

Now consume it:

declare function getUserState(): UserState;

const user = getUserState();

user.statusCode; // fine: every member has statusCode
user.data;       // error: only UserLoaded has data

statusCode is reachable because it lives in all three members, and that intersection is the only thing TypeScript lets you touch on the bare union. Reach for data and the compiler stops you: it can’t prove you aren’t holding a UserLoadFailed.

Add a literal field to discriminate

Give every member a status field typed as a string literal. That one field is the discriminant:

interface UserLoadFailed {
  status: "failed";
  statusCode: number;
  message: string;
}
interface UserLoading {
  status: "loading";
}
interface UserLoaded {
  status: "loaded";
  data: User;
}

type UserState = UserLoadFailed | UserLoading | UserLoaded;

Check that field and TypeScript narrows the union to the one member that matches:

function render(user: UserState): string {
  switch (user.status) {
    case "failed":
      return `error ${user.statusCode}: ${user.message}`;
    case "loading":
      return "loading…";
    case "loaded":
      return user.data.name; // data is reachable: narrowed to UserLoaded
    default:
      return assertNever(user); // compile error if a state goes unhandled
  }
}

function assertNever(x: never): never {
  throw new Error(`unhandled state: ${JSON.stringify(x)}`);
}

Inside each case, user is the specific member, so its unique fields are reachable and type-safe. The default branch is where exhaustiveness pays off: assertNever accepts a never, so if you add a fourth state and forget a case, user is no longer never there and the build fails. The states become impossible to drop silently.

The TypeScript handbook goes deeper on unions and intersections.

Dockerizing a NestJS app and debugging it in VS Code

Tue, 24 Nov 2020 00:00:00 GMT

Running a Node app in a container is the boring part. The part people give up on is keeping breakpoints working once the code moves inside the container. This walks through packaging a NestJS app into a Docker image, running it with Compose, and attaching the VS Code debugger to the process inside so your TypeScript breakpoints still land. Nothing to copy blind: every line earns its place.

What you need

NestJS CLI: npm i -g @nestjs/cli
Docker and Docker Compose: the container runtime and the orchestrator on top of it
VS Code: for the debugging half

Scaffold the app

nest new <app-name> bootstraps the project and asks which package manager you want. You get the standard Nest layout:

Write the Dockerfile

Two files at the project root:

touch Dockerfile .dockerignore

Base the image on the official Node LTS image, install dependencies first, then copy the source:

FROM node:lts
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["npm", "run", "start"]

Copying package*.json and running npm install before COPY . . is deliberate. Docker caches each layer, so as long as your dependencies don’t change, editing source code skips the reinstall entirely. Installing inside the image rather than copying node_modules from the host also means native modules compile against the image’s Linux toolchain instead of your laptop’s.

The .dockerignore keeps host artifacts out of the build context:

dist
node_modules
*.log

node_modules stays out so the host copy never shadows the one built in the image; dist stays out so a stale local build can’t leak in; logs are noise.

Build and run

docker build -t my-app:1.0.0 .
docker run my-app:1.0.0

build bakes the image; run starts a container from it and pipes its output to your terminal. Ctrl+C stops the container. Run it detached with -d to keep it alive, then docker exec into it or docker stop <container> when you’re done.

Move to Compose

Running one container by hand is fine. Running several (a backend, a database, a queue) by hand is not. Compose describes the whole set in one file and brings it up with one command:

services:
  backend:
    build:
      context: .
    image: my-app:1.0.0
    environment:
      NODE_ENV: development
      PORT: 3000
    ports:
      - 3000:3000
      - 9229:9229 # node debug port
    volumes:
      - /app/node_modules # keep the image's node_modules
      - ./:/app # live-mount source for hot reload and sourcemaps

The two volumes only work as a pair. ./:/app mounts your source into the container so saves hot-reload, and the bare /app/node_modules anonymous volume shields the image’s dependencies from being clobbered by that mount. Port 9229 is Node’s debug port, and exposing it is what makes the next step possible.

Bring it up:

docker compose up -d

Without Compose, the equivalent docker run is a wall of -p, -e, and -v flags, and that’s for one service. Multiply by eight and the file has already paid for itself.

Attach the VS Code debugger

Start Nest in debug mode, bound to 0.0.0.0 so the debugger is reachable from outside the container:

// package.json
"start:debug": "nest start --debug 0.0.0.0:9229 --watch",

Override the container’s command to use it:

    command: npm run start:debug

In VS Code, open the Run panel and create a launch.json:

Configure an attach:

The fields that carry weight:

request: "attach": connect to the debugger already running inside the container instead of launching a new process
port: 9229: Node’s default debug port, the one you exposed in Compose
address: "127.0.0.1": reachable because Compose maps that port onto your host
localRoot / remoteRoot: map your project path on the host to /app in the container, so breakpoints line up with the code running inside
sourceMaps: true: Nest ships TypeScript sourcemaps by default, so a breakpoint in a .ts file resolves to the compiled .js at runtime
restart: true: reattach after hot reload drops the connection, which it does every time you save

Set a breakpoint, save, and it hits inside the container:

If you rolled your own project instead of using the Nest CLI, turn on sourceMap in tsconfig.json first. Without it, breakpoints have nothing to map to.

The finished project is on GitHub.