DEV Community: Joan Miquel Torres

Agentp: Turn OpenCode Into a Headless AI Engine for Your Editor, Terminal, and Telegram

Joan Miquel Torres — Wed, 17 Jun 2026 22:26:14 +0000

I've always felt out of step with the prevailing trends.

Before the AI explosion, the mantra was "ship fast" — the Minimum Viable Product. If you weren't first, you were nobody. Quality, testing, documentation? Nice-to-haves. I could never stomach shipping "human slop" just to be first.

Now we're in the AI era, and suddenly everyone is alarmed about "AI slop." And I find myself out of step again — because from where I stand, the AI helps me produce the opposite.

Just as an example, I have a personal side project called SmarkForm and very little time to invest in it (but I keep pushing). Before AI it had a few "not-to-break-again" tests and a bare "just-the-docs" Jekyll site on GitHub Pages with often outdated code snippets and only a separate Examples section (which still exists) as the sole real demo.

Nowadays almost every code snippet in the documentation is a working example of a SmarkForm-powered form whose source code can be edited in place. The test suite has been fully migrated to Playwright, covering up to 5 platforms and including a suite of co-located tests that ensure every example in the documentation keeps working. Moreover, the most recent inline examples are AI-authored (in Copilot's words: "SmarkForm's clean, declarative API makes it a natural fit for AI-assisted development"). The last "AI-free" bastion in the repository was the actual source code of the library, but nowadays I use AI there too — just with a more thorough review and a test-first approach.

Put simply: my documentation is better. I write more tests than I could have imagined before. The code is cleaner. Even the worst AI-generated test is harmless: the most it can do is be useless. Unlike buggy production code rushed out to win a race, it won't break anything — an occasional garbage-collection pass is all you need.

The same goes for tooling. Every few years — sometimes months — a new IDE becomes the baseline, and if you haven't switched you're suddenly irrelevant. I use Neovim and tmux. Not because they're trendy, but because I spent years evolving a workflow that works across physical terminals, remote servers, and whatever machine I happen to be sitting at. And, more importantly, it lets me focus on what I'm doing rather than how to do it. I'm not about to throw that away for a shinier editor.

That's the mindset behind the agentp trio. It started with just agentp, a simple CLI tool that pipes a prompt to an OpenCode server and returns the final answer while you see what's going on in a spare monitor (when you have it). Then came ocmux, a project manager that manages a tmux session labeled as "Opencode" and keeps a dedicated OpenCode server and TUI for each project in a separate window. Finally, tgagentp is a Telegram bot that lets me talk to my projects (and even send and receive files) while away from the keyboard — and so much more.

Agentp grew from there — piece by piece, idea by idea — into a set of three zero-dependency Node.js CLI tools. It's heavily AI-assisted, including the tests. I review every stage before shipping, but the real test is using it every day. Bugs happen; I value a working feature more than a flawless one.

In summary, now I can:

Pipe a prompt straight from Vim and replace my selection with the answer.

See what's going on in an Opencode TUI that automatically switches to the right project.

Get notified in Telegram when the answer is ready.

Talk to the agent in charge of my project from Telegram while away from the keyboard.

Handle multiple projects and servers simultaneously from a Telegram group with topics.

Queue messages while a server is busy and get threaded replies.

Leave private comments and public (for the agent awareness) notes in my telegram conversation.

Send files to the agent and ask the agent to send files to me through Telegram.

Record a Telegram conversation and inject it as context into the next agentp response.

Threaded replies, permission request handling, and more...

The Three Tools

`agentp` — The Pipe

Stdin in, answer out. That's the core loop.

When you get used to writing text in Vim, all other text input methods feel clunky — and OpenCode TUI's editor is no exception. Its /editor command lets you edit prompts in an external editor, but the whole TUI screen blanks out during the edit, which means a complete loss of context.

My solution: I open the OpenCode TUI in a dedicated tmux session that I can maximize on a spare vertical monitor or just switch back and forth when working from a laptop. Then I write my prompts directly in Vim, visually select them, and send them to OpenCode by filtering them through agentp. I can either ask for a code snippet and get the answer in place, or use the --qa modifier to keep my prompt together with the answer. The latter lets me maintain a kind of logbook of prompts and answers so I can go back to review, copy chunks of code (or former prompts), etc.

Basic usage:

printf "Summarize this file" | agentp
cat prompt.txt | agentp

# Target a specific session by name (partial match works)
cat prompt.txt | agentp --session "My Task"
cat prompt.txt | agentp --session "New Task" --new   # create if not found

# Pull the last N answers without sending a new prompt
agentp --getLast 5
agentp --getLast 3 --qa    # full QA pairs with rulers

Real magic from Vim/Neovim:

:'<,'>!agentp --qa

This replaces your visual selection with the answer. The optional --qa modifier preserves the prompt + answer with labels, so you keep the full context.

🚀 Spoiler:

Passing the output of ocmux (without arguments) ensures the prompt goes to the right server and automatically switches the TUI in your spare monitor (or wherever) to the right project, instantly.
:'<,'>!agentp --qa $(ocmux)

`ocmux` — The Project Manager

Each project gets its own tmux window with a dedicated opencode serve + TUI pane. Auto-restarts dead panes, pins window names, stores state in .ocmux.json (discovered upward like .git).

Having the OpenCode TUI aside while you send work to it and receive answers in place is great. But what if you want to switch to another project while the agent is processing?

Open another OpenCode Server + TUI in a new tmux window.
Remember the port of each server.
Manually switch to the right TUI pane and zoom it.
Pass the correct port to agentp every time you call it from a different directory…

None of this is a big deal on its own. But by the time you finish working on the second project, the first one has probably finished — and you'd want to switch back.

Ocmux handles all of that. With no arguments, it switches the Opencode tmux session to the window for the current project (based on the working directory) and prints the server URL.

Combine it with agentp as agentp $(ocmux) or agentp --qa $(ocmux) and you not only send the prompt to the right server and get the answer back — at the same time, OpenCode automatically switches to the right TUI window for that project. It feels like magic when you're juggling multiple projects.

ocmux serve ~/projects/myapp        # create (new window)
ocmux serve --print-logs ~/projects/myapp  # also print server logs to terminal
ocmux list                          # list all
ocmux list -l                       # list with full URLs
ocmux ~/projects/myapp              # switch (shows url)
ocmux                               # same as ocmux $(pwd)
ocmux kill ~/projects/myapp         # remove
ocmux kill                          # same as ocmux $(pwd)

ocmux also supports --git and --GIT flags for git base directory resolution: --git matches with either worktrees or repository roots, while --GIT requires an actual repository root (not a worktree).

ocmux --last prints the URL of the active tmux window — useful when calling agentp from outside the project directory.

When an opencode server crashes, ocmux resurrect reads .ocmux.json, kills the stale tmux window, and starts a fresh server + TUI in the same directory. Works even with a dead tmux window (stale state file).

`tgagentp` — The Telegram Bridge

A Telegram bot that routes messages to your OpenCode servers. Multi-chat, multi-server, slash-commands for everything.

Ever wanted to work on a project while away from the keyboard? Writing notes is fine, but you get no feedback — you can't see or explore the project environment. What if you could send a prompt to an agent handling your project and get the answer back in Telegram? Queue messages while the server is busy and get threaded replies? Send files to the agent, or — even better — ask the agent to send files to you?

That's tgagentp. And way more: handle multiple servers simultaneously (with a Telegram group using topics), "record" your messages so the next agentp --qa prepends the conversation as context… And vice versa: get prompts and responses from agentp --qa delivered to Telegram so you can follow the conversation from anywhere — or just go grab a coffee and get notified when the agent finishes.

tgagentp                                  # default port 4096
tgagentp --think                          # start with thinking forwarding enabled
tgagentp --dev                            # enable /shutdown for remote restart
TGAGENTP_ROOT=/srv/projects tgagentp      # enable /serve and /new commands
TGAGENTP_ALLOWED_CHAT_IDS="123,-456" tgagentp  # restrict to specific chats

Slash commands:

Command	What it does
`/help`	Show available commands
`/status`	Show current server, session, agent, and health
`/servers`	List/switch between ocmux projects
`/sessions`	List/switch/create/rename sessions
`/agents`	List/switch active agent
`/models`	List providers and models
`/serve <path>`	Start a server in an existing project (requires `TGAGENTP_ROOT`)
`/new <path>`	Create a directory, init git, and start a server (requires `TGAGENTP_ROOT`)
`/allow`	Approve a tool permission once
`/reject`	Deny a tool permission
`/always`	Approve a permission and remember the choice
`/answer <number>`	Respond to a structured question from the AI
`/markdown`	Send original markdown response as `.md` file (reply to get that specific one)
`//<command>`	Send a raw TUI command (e.g., `//init`, `//clear`) — answer or confirmation forwarded
`/queue <msg>`	Queue message when busy — auto-sent after current task finishes (replies chain!)
`/record`	Record / pause / retrofill conversation for `agentp` context
`/flush`	Clear all queued messages (manual or auto-queued)
`/note <text>`	Forward context for agent awareness (agent replies "Ack", info informs future responses)
`/comment <text>`	Save a comment in chat (not forwarded to agent — context via reply quoting)
`/think`	Toggle real-time thinking message forwarding
`/cancel`	Abort the running prompt
`/disconnect`	Disconnect from current server, clear ownership and connection file
`/force-switch <server>`	Switch server bypassing ownership check (two-phase matching)
`/resurrect`	Restart a crashed server and reconnect the chat to the new instance

Permission prompts from OpenCode (tool access requests) are forwarded automatically — respond with /allow, /reject, or /always directly in the chat.

When the AI asks a structured question (e.g., tool configuration), tgagentp forwards it as a numbered multiple-choice poll — respond with /answer <number>. If the command produces a quick answer, it arrives immediately; otherwise a confirmation (✅ /init submitted.) is sent.

File sharing: Ask the agent to send you a file and it will know how. Send a file to the chat and the agent will be notified and can download it on demand.

!! wildcard: Use !! in any command to reference the previous user message. For example, /queue !! queues your last message, /note !! sends it as a note.

On formatting: The agent produces Markdown, but Telegram only supports a limited subset (bold, italic, code, pre). tgagentp converts Markdown to Telegram's HTML automatically, which works great for prose, lists, and code — but complex tables, nested formatting, or raw HTML may not survive the trip. If something looks mangled, use /markdown to download the original response as a .md file and read it comfortably in any Markdown viewer or editor.

`agentp` and `ocmux` together

Combine both tools and you never need to think about ports or URLs again. agentp $(ocmux) sends your prompt to the right server for the current project AND switches the TUI to show that project — all in one command. From Vim:

:'<,'>!agentp --qa $(ocmux)

Note: You may think you can just run ocmux once and pass the URL as a
literal to agentp — the command is recorded in your Vim command history, after all.

But calling ocmux every time also automatically switches the TUI to the
right project in the "Opencode" tmux session. That's the real value.

The Agentp Gateway

The killer integration: agentp and tgagentp talk to each other through a tiny HTTP gateway.

agentp --tg — forwards the answer to your Telegram chat after every pipe (hard error if tgagentp not running).
agentp --no-tg — explicitly disable Telegram forwarding (overrides auto-detection in --qa mode).
agentp --qa — auto-detects tgagentp and sends the full QA pair (rulers + prompt + answer) if tgagentp is running.
/record — buffers the Telegram conversation. On the next agentp call, the gateway returns the buffer, and --qa prepends it to stdout with rulers — so OpenCode sees the full Telegram thread as context. Retroactively buffer past messages with /record N.
agentp --flush — clears the buffer without prepending.
agentp --getLast 5 — retrieves the last 5 assistant answers from session history (or QA pairs with --getLast 5 --qa).
Exclusive ownership — each server belongs to at most one chat. New chats start disconnected. /servers switch <name> --force takes over and notifies the previous owner.
Auto-queue — when a server is unreachable, messages are automatically queued and delivered when it comes back. /flush clears the queue.
Server health detection — tgagentp periodically checks server connectivity. Dead servers are shown as ❌ unreachable in /status.
Multi-chat — each Telegram chat or forum thread has independent server, session, and recorder state. Perfect for teams sharing one bot.
Auto tmux switch — every message or /note from any chat/topic automatically selects and zooms the corresponding server's tmux window, so the TUI follows the conversation across topics.
Message splitting — long answers are split at 4096 characters (respecting newlines) to stay within Telegram limits.
State persistence — chat-to-server directory mappings survive restarts via /tmp/tgagentp-connections.json. On reboot, tgagentp re-discovers the live server URL from .ocmux.json and reconnects automatically. /shutdown clear wipes the saved state.
Remote resurrect — /resurrect restarts a crashed server from Telegram: calls resurrectServer() from the library, then transfers session state (serverOwners, active session/agent) to the new URL.

:'<,'>!agentp --qa --tg          " answer in editor + Telegram (hard error if no tgagentp)
:'<,'>!agentp --qa               " same + Telegram only if tgagentp detected
:'<,'>!agentp --qa --flush       " flush /record buffer
:'<,'>!agentp                    " only replaces. Useful for simple snippets.
:'<,'>!agentp --no-tg            " same as above, explicitly skip Telegram

Environment variables:

Variable	Required	Default	Description
`TELEGRAM_BOT_TOKEN`	Yes	—	Bot token from @botfather
`TGAGENTP_ALLOWED_CHAT_IDS`	No	all	Comma-separated chat IDs to allow (e.g. `"123456,-789012"`)
`TGAGENTP_ROOT`	No	—	Root directory for `/serve` and `/new` commands (must be writable)
`TGAGENTP_PORT`	No	random	Port for the agentp gateway (agentp --tg discovers it automatically)
`TGAGENTP_DEBOUNCE_MS`	No	5000	Debounce interval for queued-agentp Telegram notifications (ms)
`OPENCODE_SERVER_PASSWORD`	No	—	Password for authenticated OpenCode servers

All of this with zero npm dependencies — just Node.js 18+ stdlib.

Why This Setup Works

Always-visible TUI, hands-free — The dedicated TUI lives on a spare monitor, a virtual desktop, or a tmux window. You work elsewhere. The TUI shows the full picture without you touching it.
Multi-project agility — Each project gets its own server and TUI. Switch projects with a single ocmux command (or automatically via ocmux with no args), and the displayed TUI follows. The same auto-switch works from Telegram: every message or /note selects the right tmux window, so the TUI follows you across topics. Start a task in project A, switch to project B while A runs.
Editor ↔ terminal ↔ Telegram loop — Pipe from Vim with agentp, get the answer inline. Enable --tg (implicit with --qa) and the result also lands in Telegram — so even if you moved to another device or context, you know when it's done.
Remote awareness — tgagentp monitors progress, forwards permission prompts, and queues follow-ups from anywhere. /record recovers Telegram conversation context for your next agentp call. Notifications pop the moment a piped task finishes or needs input.
Graceful degradation — --tg in auto mode silently skips Telegram if tgagentp isn't running. Explicit --tg errors pre-send, warns post-send.
Async processing — tgagentp never blocks the polling loop. Commands stay responsive even while a prompt runs.

Quick Start

npm install -g agentp

# Start a project server
ocmux serve ~/projects/myapp

# Pipe a prompt
printf "Explain this codebase" | agentp

# With Telegram (set up a bot with @BotFather first)
export TELEGRAM_BOT_TOKEN="your-token"
export OPENCODE_SERVER_PASSWORD="your-password"   # optional but recommended
tgagentp --think

How We Gave Every Documentation Example Its Own Test — and Why It Caught Real Bugs

Joan Miquel Torres — Tue, 03 Mar 2026 17:01:24 +0000

Documentation examples have a dirty secret: they're code, but they're rarely
treated like code.

We write them carefully when we publish them, and then — slowly, quietly —
they drift. The API changes. A parameter gets renamed. The behavior shifts
slightly. Yet the docs example keeps running in our heads as the canonical
demonstration, even after it stops being accurate.

For SmarkForm — a markup-driven form
library whose entire value proposition is its declarative HTML API — this risk
is especially acute. Our documentation site is full of interactive examples.
People copy them. People trust them. If they're wrong, the library looks
broken — because to the person reading the docs, the example is the library.

This is the story of how we solved it.

The Starting Point: A Library With Living Examples

SmarkForm's documentation is a Jekyll site with dozens of
interactive playground examples.
Each example is a fully functional mini form, rendered live in the browser,
showing features like nested subforms, variable-length lists, context-driven
hotkeys, and more.

The examples aren't just screenshots — they use a component called
sampletabs_tpl that renders a tabbed interface with a live form, the HTML
source, the JavaScript source, and a JSON import/export playground. Anyone
reading the docs can click Import, tweak the JSON, and see the form respond.

That richness is exactly what makes untested examples so dangerous. There's a
lot of moving parts to get right.

The Foundation: Migrating to Playwright

Before we could build co-located tests, we had to fix the foundation. In
October 2025, the existing test suite — Puppeteer + Mocha, over 2,000 lines —
was migrated to Playwright. This wasn't just a
tooling swap. It opened the door to:

Running tests across Chromium, Firefox, and WebKit with a single command.
A much cleaner API for async interactions.
Better tracing and debugging when things went wrong.
A modern, actively maintained ecosystem.

The Playwright migration itself was a prerequisite for everything that followed.
With a solid, multi-browser foundation in place, the next question became: how
do we use it to test the documentation examples?

The Idea: Co-Located Tests

The insight was simple: put the test right next to the example.

Not in a separate test/ folder that grows out of sync. Not in a spreadsheet
of "things to manually verify." Right there, in the same Markdown file, in the
same {% capture %} block that describes the example.

Here's what it looks like in practice. A documentation example in SmarkForm's
Jekyll site looks like this:

{% capture my_example_html %}
<form data-smark>
  <input name="username" data-smark />
  <button data-smark='{"action":"export"}'>Save</button>
</form>
{% endcapture %}

{% include components/sampletabs_tpl.md
    formId="my_example"
    htmlSource=my_example_html
    tests=false
%}

The tests=false means: I know there's no custom test here; that's intentional.

But for examples where behavior matters, you add a capture block with real
Playwright test code:

{% capture my_example_tests %}
export default async ({ page, expect, id, root, readField, writeField }) => {
    await expect(root).toBeVisible();

    const input = root.locator('input[name="username"]');
    await input.fill('alice');

    expect(await readField('username')).toBe('alice');
};
{% endcapture %}

{% include components/sampletabs_tpl.md
    formId="my_example"
    htmlSource=my_example_html
    tests=my_example_tests
%}

That export default async function is a real Playwright test. It gets
extracted, executed, and reported as a test result — for every browser.

Keeping It Navigable: Vim Fold Markers

There's a side effect of co-location that isn't immediately obvious: the
documentation files get long. Very long. A single showcase page might contain
a dozen {% capture %} blocks — HTML source, CSS source, JavaScript, notes,
and now tests — each running tens or hundreds of lines.

The file is perfectly machine-readable. For a human editor reviewing or
updating a specific example, it can become a wall of text.

The SmarkForm project's solution to this is vim fold markers — a
convention borrowed directly from how src/ files are written — applied to
the Markdown documentation files as well.

In the library source code, functions are bracketed like this:

export function parseTime(str) {//{{{
    // ... implementation
};//}}}

In documentation Markdown files, capture blocks are bracketed with HTML
comments wrapped in {% raw %} to prevent Jekyll from consuming them:

{% raw %} <!-- basic_form_html {{{ --> {% endraw %}
{% capture basic_form_html %}
<p>
    <label data-smark>Name:</label>
    <input type="text" name="name" data-smark />
</p>
{% endcapture %}{% raw %} <!-- }}} --> {% endraw %}

The closing marker sits on the same line as {% endcapture %} — one
less line to scroll past. When a capture's closing %} falls on its own
line (a formatting choice sometimes made for long captures), the closing
marker follows on the next line instead.

With vim's foldmethod=marker active, every capture block collapses to a
single line — just the fold label. A documentation file with twelve captures
becomes twelve navigable lines. You can jump directly to the example you want,
expand it, edit it, and collapse it again — without losing your place in the
surrounding structure.

Enabling It

The project ships configuration files for the three most common editors, so
this works automatically once a one-time prerequisite is met.

Vim / Neovim — native support, no plugins required.

Add set exrc to your ~/.vimrc or ~/.config/nvim/init.vim once:

set exrc   " allow project-level .vimrc files
set secure " optional: sandbox project vimrc (recommended)

After that, the project's .vimrc takes over and sets foldmethod=marker
whenever you open a file in the project directory.

VS Code — install the recommended extension.

When you open the project in VS Code, you'll see a prompt to install
recommended extensions. Accept it to install
Custom Folding
(listed in .vscode/extensions.json). The .vscode/settings.json file
already configures {{{/}}} as the fold markers, so no further setup is
needed. Once installed, Fold All (Ctrl+K, Ctrl+0) collapses all marked
blocks.

Emacs — install the folding package once:

M-x package-install RET folding RET

After that, the project's .dir-locals.el enables folding-mode
automatically whenever Emacs opens a file in the project directory.

Even if your editor doesn't support fold markers natively, the pattern is still
useful: the {{{ / }}} strings are greppable labels. A quick grep '{{{' showcase.md
gives you an instant index of all captures in a file.

The Architecture: Collector + Runner

Under the hood, this works through a two-phase pipeline.

Phase 1: The Collector

A Node.js script (scripts/collect-docs-examples.js) scans the entire docs/
folder. For each Markdown file, it:

Extracts all {% capture %} blocks into an in-memory map.
Finds every {% include components/sampletabs_tpl.md %} call.
Resolves each parameter: htmlSource, cssSource, jsSource, tests, etc.
Applies transformations:
- $$ → -${formId} (ensures unique DOM IDs per example)
- █ (a filled square character) → four spaces (an indentation hack for Jekyll, which strips leading whitespace in liquid captures)
- Strips !important from CSS
Skips purely illustrative examples (jsSource="-").
Writes everything to a JSON manifest at test/.cache/docs_examples.json.

The collector also handles some subtleties. Jekyll filters like
{{ variable | replace: "old", "new" }} are simulated in JavaScript so the
resolved content is identical to what Jekyll would produce. Docs-only
parameters like demoValue (which seeds a default value in the rendered page
but is irrelevant to tests) are explicitly stripped.

Phase 2: The Runner

A Playwright test file (test/co_located_tests.tests.js) loads the manifest
and generates one test per example. For each example:

It assembles a minimal HTML page containing the example's HTML, CSS, and JavaScript, plus a <script src="/dist/SmarkForm.umd.js">.
It writes that page to a temp file and serves it via the local test server.
It navigates Playwright to the page and waits for SmarkForm to initialize.
Smoke checks always run: the form container is visible; console error and page error counts match expectations.
If tests is a code string (not "false"), the code is written to a temporary .mjs file and dynamically imported. The exported default function is called with { page, expect, id, root, readField, writeField }.

The helpers passed to each test function are worth noting:

root — a Playwright locator pointing to #myForm-${id}, the example's container.
readField(path) — exports a field's current value via SmarkForm's own .find(path).export() API.
writeField(path, value) — imports a value into a field.

This means co-located tests can test behavior at the SmarkForm API level, not
just at the DOM level. You can assert expect(await readField('price')).toBe(42)
instead of digging into the DOM for the raw input value.

The Enforcement Rule

One critical design decision: every example must declare tests=..., even
if just tests=false. If an example is missing the parameter, the test suite
fails with a clear message:

Example showcase.md_basic_form is missing co-located tests.
Please add a tests= parameter to the {% include %} block,
or use tests=false to explicitly disable testing.

This enforcement ensures the question "does this example have a test?" is
always explicitly answered. You can't accidentally omit it. The quality floor
only goes up.

The Naming Evolution

The system went through a quick naming evolution that's worth mentioning because
it reflects the conceptual clarity that emerged over time:

The first test harness was called docs_examples.tests.js — named after what it tested (docs examples).
It was soon renamed to co_located_tests.tests.js — named after the strategy (tests living alongside the code they test).
A companion file, co_located_tests_validation.tests.js, handles the meta-level: it tests the manifest itself, verifying that every example has valid tests and error-count declarations, and that transformations (no stray $$, no █ characters) were applied correctly.

The naming made it clearer that the principle — co-location — was the
important thing, not the specific mechanism.

The Workflow: Interactive Test Picking

Writing tests is one thing. Running a single test while you're developing
is another. The co-located tests are loaded and run by Playwright, which means
you can already filter them with -g and --project. But the project added
something nicer: an interactive test picker.

npm run test:pick

This drops you into an interactive shell menu where you choose:

What to test: regular tests, co-located tests (all), or co-located tests for a specific documentation file.
Which example: if you chose a specific file, which formId.
Which browser: Chromium, Firefox, or WebKit.

After selecting, it builds the right Playwright command and runs it. It also
remembers your last choice, so a --repeat flag lets you quickly re-run the
same test after changing something.

npm run test:pick -- --repeat --headed

This combination — pick once, repeat with --headed or --debug — was a
genuine quality-of-life improvement for the write-test-fix loop.

The Bugs It Caught

Here's where it gets interesting. Writing tests for existing examples
immediately surfaced bugs that had been lurking unnoticed.

The Hotkeys State Bug

While writing a test for the 2nd-level hotkeys example in the showcase, the
author (@bitifet) encoded an expectation that
seemed obvious: releasing the Alt key while Ctrl is held should return to
the 1st-level hotkeys display.

The test was committed with a note: "It fails while checking that releasing
ALT returns to previous status if Ctrl is hold. But this is a REAL bug, so
the test is Ok."

The very next commit fixed src/lib/hotkeys.js. The bug had existed in the
library, silently, until a documentation example was tested.

The datetime-local Naming Bug

When the datetime-local component type was added, a co-located test caught
a naming inconsistency: the example source used "datetimeLocal" (camelCase)
while the implementation expected "datetime-local" (kebab-case). The test
failed; the example source was corrected.

The Smoke Check Safety Net

Beyond specific behavioral tests, the smoke checks — which run for every
example — have caught examples that failed to initialize at all due to
a breaking API change. If an example produces a console error it's not
expected to, the test fails immediately. No manual clicking through the docs
required.

The Numbers

At the time of the 0.12.6 release (which introduced co-located tests), the
library described it this way in the changelog:

Major improvements to testing infrastructure and coverage:

Migrated the test suite to Playwright, covering Chromium, Firefox, and WebKit.

Added smoke tests for all examples in the documentation.

Co-located, feature-specific tests for each example are now possible — and enforced.

The suite covers dozens of interactive documentation examples, each exercised
across three browsers, all driven by the same living documentation that users
read and trust.

What Makes This Approach Work

A few principles made the co-located test strategy effective in SmarkForm:

1. The test is right next to what it tests.

There's no context-switching between "the docs example" and "the test for the
docs example." They're in the same file, a few lines apart. When you update
the example, you immediately see its test and update it.

2. Tests are enforced, not optional.

The "you must declare tests= or tests=false" rule means there's no
ambiguity. It's not a linting warning; it's a test failure. Every example is
accounted for.

3. The test interface is ergonomic.

The readField / writeField helpers let you interact with the form at
the SmarkForm API level. You don't have to know whether a number field renders
as an <input type="number"> or something else — you just call
readField('price') and assert on the returned value.

4. The test picker reduces friction.

When testing one specific example in one specific browser is two menu selections
away, you do it more often. Lower friction → more tests written → more bugs
found earlier.

5. The examples are isolated.

Each example gets its own minimal HTML page, its own SmarkForm instance, its
own error tracking. There's no bleed-through between examples. The smoke checks
for one example don't affect another.

Takeaways for Your Own Project

If your project has a documentation site with interactive examples, here's the
core idea distilled:

Treat documentation examples as first-class test subjects. They're not
just prose — they're code that runs in your users' browsers (or in their
heads when they copy-paste). Test them.
Put the test near the example. The closer the test is to what it tests,
the more likely it will be maintained. Co-location is the key.
Enforce test presence. An optional test is a test that won't get written.
Make it a breaking build failure when a test is absent and undeclared.
Invest in ergonomic helpers. The test interface should feel natural to
someone who knows the library API. If writing a test requires knowing the
DOM structure, that's a leaky abstraction.
Make the test loop fast. A test picker, a --repeat flag, a --headed
mode — any investment in the write-test-fix loop pays compound interest.

Conclusion

Co-located tests for documentation examples started as an experiment in the
SmarkForm project and quickly became one of the most practically impactful
improvements to the development workflow. They've caught real bugs — bugs that
had existed in the library, invisible, until someone wrote down what the correct
behavior should be and a test confirmed it wasn't.

More than the bugs, though, what co-located tests provide is confidence — the
confidence to refactor, to add a feature, to change a behavior, and know that
the documentation examples will tell you immediately if you've broken something
that matters.

Documentation and tests have always had a troubled relationship. Co-location is
one way to give them a common home — and to stop treating the docs as a place
where bugs go to hide.

SmarkForm is an open-source, markup-driven form library for building complex
HTML forms with nested subforms, variable-length lists, and JSON import/export.
→ smarkform.bitifet.net · GitHub

Generating a Parametric SVG Logo with Pug

Joan Miquel Torres — Mon, 02 Feb 2026 23:22:00 +0000

Designing a logo is usually treated as a one-off, visual task.
Designing a logo system—with variants, themes, sizes, and guarantees of consistency—is a very different problem.

In this article I’ll show how I ended up generating real SVG logo files, fully parametric, using Pug, embedded and subsetted fonts, and a CLI-driven pipeline.

This approach has been used to create a new SmarkForm logo, which will replace the current one starting from upcoming version 0.13.0.
The logo is not just an asset anymore: it is generated, reproducible, and version-controlled.

SmarkForm is a free and open-source toolkit for declarative, markup-driven form generation — from simple inputs to complex nested forms and dynamic lists, with first-class JSON import/export. It is framework-agnostic and styling-agnostic by design, and that same philosophy now applies to its branding.

The Goal

I wanted:

A single logo definition
Variants for:
- light / dark
- monochrome
- compact / full
Fonts embedded and subsetted
Output as real .svg files
Generated via CLI, not a browser
Reproducible and scriptable

In short: branding as code.

Why Pug?

Pug gives you three things that are surprisingly powerful for SVG work:

Logic (conditions, defaults, variants)
Parametrization (options passed from CLI)
Readable structure for complex SVG trees

SVG is XML.
Pug is extremely good at generating structured XML.

That combination is criminally underrated.

Turning SVG into a First-Class Template

The key decision was this:

Don’t generate HTML that contains SVG.
Generate SVG directly so that it can be linked everywhere.

That means:

doctype svg instead of (default in Pug) doctype html
The root node is <svg>
Follow svg specs

A Pug mixin as the logo engine

Implementing the svg as a Pug mixin let me actually start with an HTML document showcasing different parameters combinations.

Even colors and fonts were originally parametyzed allowing to examine several configurations side by side until the winner was choosen.

At the end of the process only functional parameters have been kept.

mixin smarkformLogo(options = {})
  -
    const {
      mode = 'light',
      compact = false,
      monochrome = false,
      size = 100
    } = options;

    const height = size;
    const width  = compact
      ? Math.round(height * 1.105)
      : Math.round(height * 4.1);

  svg(
    xmlns="http://www.w3.org/2000/svg"
    width=width
    height=height
    viewBox=`0 0 ${width} ${height}`
    role="img"
    aria-label="SmarkForm logo"
  )
    // SVG content here

At this point we already have something valuable:

Dimensions are computed
Variants are driven by data
The SVG is no longer static

Choosing and Subsetting Fonts

External fonts are fragile:

Network-dependent
Inconsistent
Sometimes forbidden in branding assets

So the decision was to embed the font directly in the SVG.

Picking a font with the right license

For SmarkForm I used Work Sans, available from
👉 https://fonts.google.com

Google Fonts is particularly useful because you can filter by:

Open-source licenses (SIL Open Font License, Apache 2.0, etc.)
Font weights
Variable fonts

This makes it easy to ensure your branding assets are legally safe to embed and redistribute.

Subsetting the font

Instead of embedding a full font file, I generated subsetted WOFF2 files containing only the glyphs actually used in the logo.

This keeps the SVG:

Smaller
Faster to load
More intentional

Tools like pyftsubset (from fonttools) are perfect for this step.

Examnple:

pyftsubset static/WorkSans-Regular.ttf \
    --text="<SmarkForm}" \
    --flavor=woff2 \
    --output-file=WorkSans-SmarkForm-Regular.woff2

In my case, for stylistic reasons, I used two different faces of the font so I had to do this twice (once for WorkSans-Regular and one for WorkSans-SemiBold).

You can stick with one or pick for even different fonts. I reckon keeping things simpler is better for a logo though.

Embedding Fonts via Base64

Once you have your subsetted .woff2, embedding it is straightforward.

From the shell:

base64 < WorkSans-SmarkForm-Regular.woff2

Then inline it into the template.

A small stylistic trick I used:

const WorkSans_regular_b64 = (`
  base64 < WorkSans-SmarkForm-Regular.woff2
`).replace(/\s+/g, '');

Notes:

Declaring binary (base64) data in a variable at the beginning keeps the actual code cleaner afterwards.
The backticks sit outside the base64 block, so alignment stays clean.
Newlines and spaces are stripped afterwards (avoiding css issues).
Assuming the file is in the current directory, in Vim you can simply type :vip!bash to insert in place the file contents encoded in base64.

A subtle but important detail

Base64 itself allows arbitrary whitespace and newlines.
CSS does not.

If you forget to strip whitespace, your font may silently fail to load.
This is one of those details that’s obvious after you hit it once.

Wiring Fonts to SVG Text via CSS

Fonts are referenced via CSS inside <defs>:

defs
  style.
    @font-face {
      font-family: 'WS-Regular';
      src: url('data:font/woff2;base64,#{WorkSans_regular_b64}') format('woff2');
    }

    @font-face {
      font-family: 'WS-SemiBold';
      src: url('data:font/woff2;base64,#{WorkSans_SemiBold_b64}') format('woff2');
    }

    text.regular {
      font-family: 'WS-Regular';
      dominant-baseline: middle;
    }

    text.semibold {
      font-family: 'WS-SemiBold';
      dominant-baseline: middle;
    }

The .regular / .semibold classes don’t mean anything special by themselves —
they’re simply a clean way to bind specific font weights and behaviors to specific parts of the logo.

Rendering Text Safely in SVG

One small but important gotcha when generating SVG with Pug:

text.regular(
  x=lmargin
  y=height / 2
  font-size=height * 0.6
  fill=primaryColor
)='<'

The < must be passed as a string.

Otherwise it’s interpreted as markup and breaks the SVG.
Once you do this explicitly, Pug behaves exactly as expected
by replacing them with their correspondent HTML entities.

Compact vs Full Variants (Same Source)

With logic in place, variants are trivial:

if compact
  text.semibold(...) 'S'
  text.semibold(...) '}'
else
  text.regular(...) '<'
  text.semibold(...) 'Smark'
  text.semibold(...) 'Form'
  text.semibold(...) '}'

No duplication.
No parallel files.
One definition, many outcomes.

Generating Real SVG Files from the CLI

This is the payoff.

Once the template outputs only SVG, you can do this:

npx pug-cli \
  -O '{ compact: true, mode: "dark" }' \
  < smarkform_logo.pug \
  > smarkform_compact_dark.svg

And that file is:

A valid SVG
Fully self-contained
Embeddable anywhere
Diff-friendly
Reproducible

You can script all variants in seconds.

Integration into the SmarkForm project

Integrating the new logo into the SmarkForm codebase turned out to be refreshingly simple.

The existing assets already lived under /docs/assets, so I introduced a new logo directory for better organization, with a src subdirectory to hold the source files.

The Pug template that generates the logo variants now lives in /docs/assets/logo/src, alongside a small Bash script responsible for rendering the desired SVG outputs. The script is intentionally minimal and largely self-documenting, making it easy to adjust or extend if new variants are needed in the future.

Importantly, this script is not part of the build process. The generated SVG files are stable, self-contained assets and remain valid until the logo source itself changes. In practice, this means the script only needs to be executed when the Pug template is modified—keeping the build pipeline clean and avoiding unnecessary regeneration work.

You can find both the generator template and the accompanying script in the aforementioned /docs/assets/logo/src directory in the SmarkForm GitHub repository.

Why This Scales

This approach scales because:

Logos become data-driven
Branding lives inside the repository
Changes are auditable
Variants never drift out of sync

Just as importantly, it respects SmarkForm’s philosophy:

SmarkForm is markup-driven and styling-agnostic.

The branding system does not impose a visual identity on user forms.
Instead, it provides optional, lightweight visual cues — icons or small banners — so end users may recognize a form as being powered by SmarkForm and know what kind of experience to expect.

Developers and designers remain fully in control.

Final Thoughts

This started as “I just want a logo SVG”.

It ended as:

A parametric branding system
A CLI-driven asset pipeline
A single source of truth

If you already treat UI as code,
there’s no good reason your branding assets shouldn’t be treated the same way.

Once you do it like this, going back feels… unnecessary 😉

PostgreSQL and high availability in Node.js

Joan Miquel Torres — Mon, 12 Aug 2024 17:54:04 +0000

For those using PostgreSQL with Node.JS and worried about High Availability and outage resilience, I have published this wrapper solving important issues in node-pg:

https://github.com/bitifet/node-postgres-ha

I am looking forward to cherry-pick the improvements as PRs to actual node-postgres but, by now, it fits our goals of preventing issues derived from eventual server or network malfunctions.

Simulate TCP network congestion with netjam

Joan Miquel Torres — Tue, 06 Aug 2024 21:24:17 +0000

Network issues always come in production.

We tend to, at most, perform some stress tests to check what happen in
(unrealistic) high load situations or even stop some critical services,
like databases, to see how resilient is our application or service..

But the truth is that there can be worst situations...

I mean: If your database goes down, you'll rapidly get errors due to TCP
connection attempts being rejected.

But, when network speed decreases due to the amount of traffic, network errors,
etc... You may end up with lots of pending requests that will never end causing
much more trouble that could be easily avoided if we had properly detected the
situation.

To be able to address that situations we need to reproduce them, at least at
some level.

As a first approach, I tried with iptables DROP rules, but this is drastic
solution: Either you have a perfect connection or all packets are lost. And I
wanted to play with several PostgreSQL
timeouts and their effect in
different situations.

Finally I ended up implementing my own tool to simulate different levels of
traffic congestion:

I don't know if there are other similar tools out there (at least I haven't
found any until now: If you know any, please tell me in the comments).

...And it's still far from perfect.

But, at least, it helped me to learn a lot about how PostgreSQL timeouts work
and the effects they can have in different situations.

And it is a very simple-to-use tool. Specially now that I bundled it as a npm
package so that, if you have Node/NPM in your system, you only need to execute
the following to get started:

npx netjam --help

For example, to create a jamable TCP tunnel to local PostgreSQL Server
listening in its default port (5432) you only need to execute the following
command:

npx netjam localhost 5432

Then you will get something like this:

Server listening on port 5000

STATUS:
┌─────────────┬────────────────────────────┐
│   (index)   │           Values           │
├─────────────┼────────────────────────────┤
│ remoteHost  │        'localhost'         │
│ remotePort  │           '5432'           │
│ listenPort  │            5000            │
│  timestamp  │ '2024-08-06T18:52:11.042Z' │
│   waiting   │             0              │
│    open     │             0              │
│   closed    │             0              │
│  withError  │             0              │
│     tx      │             0              │
│     rx      │             0              │
│  iputDelay  │             0              │
│ outputDelay │             0              │
│ logInterval │       '0 (Disabled)'       │
└─────────────┴────────────────────────────┘

AVAILABLE COMMANDS:
  inputDelay    - Sets input delay to specified value
  outputDelay   - Sets output delay to specified value
  delay         - Sets overall balanced delay to specified value
  logInterval   - Show/Set status (stderr) logging interval in msecs
  quit          - Quit the program

>

By now it is capable to speed down transmission and reception speed by
introducing small delays between packet transmission and reception at the other
side.

In the future it could be extended by introducing:

Random (on customizable probability) transmission errors through data
mangling.
Random packet loosing.
Delay configuration as ranges (so it will take a random value between given
bounds for each tx/rx packet.
Who knows... Any ideas?

Simplify Web Form Development with SmarkForm

Joan Miquel Torres — Fri, 07 Jul 2023 11:28:00 +0000

Introduction:

Creating web forms can often feel like reinventing the wheel. Every time we need to implement a form, we find ourselves going through the same process.

For simple forms with a few plain fields, it may be pretty straightforward. However, as soon as we need a little more complexity, such as lists, nested data, dynamic options, and more, it can quickly become a time-consuming and effort-intensive task that diverts our focus from the core functionality of our applications. But fear not! With SmarkForm, you can break free from this repetitive cycle and streamline your form development process.

SmarkForm is a powerful and straightforward JavaScript library that will greatly simplify form development in your web applications. With SmarkForm, you can quickly and efficiently create interactive forms without having to worry about writing complex JavaScript code.

What is SmarkForm?

It is based on the idea that web forms should be easy to create and maintain directly in HTML markup, without the need for writing a lot of additional JavaScript code.

We just need to add a few properties in so-called data-smark attributes to make our HTML markup more semantic and let SmarkForm library do the rest.

Key Features of SmarkForm:

Easy and quick creation of interactive forms.
Complete separation between layout design and application logic.
Support for complex data structures, such as nested objects and arrays.
Ability to manually sort and add or remove items from a lists (arrays).
(Comming soon) Dynamic loading of options for select fields based on the values of other form fields.
Customization and extensibility through custom components.

Try it yourself:

Learn more about SmarkFor in its Documentation site.

Don't miss its examples section where you can check out its HTML source and JS example.

Smarkform is available both as standard ESM and legacy UMD modules in npm package and CDN.

Former examples use UMD CDN so that they can be downloaded as single and fully functional HTML pages.

It's styles are also served as separate CDN but you can use your own styling.

Feel free to play modifying them as you like.

Questions:

If you have any questions or if you find this article unclear or incomplete, please let me know.

I've made an effort to be approachable and prevent it from being tedious by excluding certain details that can already be found in the documentation and examples.

However, if you believe that something is lacking, please provide your feedback in the comments.