Christian Helle’s Blog

Reviving a 15 year old XNA Framework game with MonoGame

2026-03-24T00:00:00+00:00

I recently revived Chris’ Puzzle Game, an old sliding puzzle game I originally wrote for Windows Mobile then re-wrote using XNA for Windows Phone. The result is a modern MonoGame port that targets current versions of .NET and runs as a desktop application on Windows.

What made this project especially interesting is that I did not port it the traditional way. This was a pure agentic engineering exercise using GitHub Copilot CLI together with Squad. I gave the agents a goal, pointed them at the original repository, and let them work through the migration with the old game as the behavior reference.

This post is a walkthrough of that rewrite: what the original XNA code looked like, what changed in the MonoGame version, how the gameplay logic was modernized, and why this was an ideal kind of project for agentic engineering.

The prompt

The prompt I used was intentionally short:

Build a MonoGame port of my old XNA Framework based game for Windows Phone called Chris' Puzzle Game. My old puzzle game is open source and the code is available at https://github.com/christianhelle/xnapuzzlegame

That is not much of a specification, but it contains the most important part: a concrete reference implementation.

The original repository gave the agents a playable target to aim for. That meant the job was not to invent a puzzle game from scratch. The job was to preserve the feel of an existing game while replacing the platform underneath it. In practice that meant keeping the screen flow, puzzle behavior, preview mode, and overall structure intact while adapting input, window management, persistence, and the build pipeline for modern desktop .NET.

Revisiting the original XNA codebase

The original XNA repository is more complete than the very first prototype I wrote about in my old post Writing a puzzle game for Windows Phone 7. The open source version includes a proper screen manager, a main menu, credits, preview mode, in-game options, and save/resume support through isolated storage.

At the top level, the startup flow is very XNA-era in spirit: create the graphics device, attach a screen manager component, and then restore the previous screen stack or fall back to the main menu.

public PuzzleGame()
{
    Content.RootDirectory = "Content";

    graphics = new GraphicsDeviceManager(this);
    TargetElapsedTime = TimeSpan.FromTicks(333333);

    screenManager = new ScreenManager(this);
    Components.Add(screenManager);

#if WINDOWS_PHONE
    if (!screenManager.DeserializeState())
    {
        screenManager.AddScreen(GameScreenFactory.Create<BackgroundScreen>(), null);
        screenManager.AddScreen(GameScreenFactory.Create<MainMenuScreen>(), null);
    }
#else
    screenManager.AddScreen(GameScreenFactory.Create<BackgroundScreen>(), null);
    screenManager.AddScreen(GameScreenFactory.Create<MainMenuScreen>(), null);
#endif
}

The main menu itself was simple and direct, which is exactly what made it easy to preserve in the port:

public MainMenuScreen()
    : base("Chris' Puzzle Game")
{
    var playGameMenuEntry = new MenuEntry("New Game");
    var aboutMenuEntry = new MenuEntry("About");
    var exitMenuEntry = new MenuEntry("Exit");

    playGameMenuEntry.Selected += PlayGameMenuEntrySelected;
    aboutMenuEntry.Selected += AboutMenuEntrySelected;
    exitMenuEntry.Selected += OnCancel;

    MenuEntries.Add(playGameMenuEntry);
    MenuEntries.Add(aboutMenuEntry);
    MenuEntries.Add(exitMenuEntry);
}

Most of the interesting logic lived in GameplayScreen. That class was responsible for almost everything: loading the puzzle image, slicing it into tiles, scrambling the board, reading input, tracking time, checking for completion, drawing the puzzle, and serializing progress. It worked, but it also mixed game rules, rendering, and persistence into one large screen class.

That combination is very typical of small XNA projects. It is also exactly the kind of codebase that benefits from a rewrite rather than a literal line-by-line port.

Moving from XNA and Windows Phone to MonoGame and .NET 10

One of the first changes in the MonoGame port was simply choosing a modern runtime and packaging model. Instead of an XNA project targeting Windows Phone, the new project targets net10.0 and references the MonoGame desktop framework directly.

<PropertyGroup>
  <OutputType>WinExe</OutputType>
  <TargetFramework>net9.0-windows</TargetFramework>
  <UseWindowsForms>true</UseWindowsForms>
  <ApplicationHighDpiMode>PerMonitorV2</ApplicationHighDpiMode>
  <Nullable>enable</Nullable>
</PropertyGroup>

<ItemGroup>
  <PackageReference Include="MonoGame.Framework.WindowsDX" Version="3.8.*"/>
</ItemGroup>

That change alone immediately moves the game from the XNA/Windows Phone world into something that can be built with current .NET tooling. The port also wires the MonoGame content pipeline into MSBuild so content is rebuilt as part of the project build:

<Target Name="BuildMonoGameContent"
        Condition="'$(DesignTimeBuild)' != 'true'"
        DependsOnTargets="RestoreMonoGameTools"
        BeforeTargets="CopyFilesToOutputDirectory">
  <Exec WorkingDirectory="$(MSBuildProjectDirectory)\Content"
        Command="dotnet mgcb /@:Content.mgcb /rebuild /quiet"
        StandardOutputImportance="Low"/>
</Target>

The new startup code still feels recognizably like the original game, but it is now clearly desktop-first:

public PuzzleGame()
{
    Content.RootDirectory = "Content";
    gameplayPersistence = new();

    _ = new GraphicsDeviceManager(this)
    {
        PreferredBackBufferWidth = 1200,
        PreferredBackBufferHeight = 720,
        SynchronizeWithVerticalRetrace = true,
    };

    TargetElapsedTime = TimeSpan.FromSeconds(1d / 60d);
    IsMouseVisible = true;
    Window.AllowUserResizing = true;
    Window.Title = "Chris' Puzzle Game";

    screenManager = new(this);
    Components.Add(screenManager);
    Exiting += HandleGameExiting;

    ConfigureStartupScreens();
}

The shape is familiar, but the assumptions are different. The port is not pretending to be a phone game anymore. It is a Windows desktop game with a resizable window, visible mouse cursor, high DPI support, and an explicit persistence service that saves state on exit.

Extracting the puzzle rules into a real board model

One of the most useful improvements in the rewrite was separating the board logic from the screen class.

In the original GameplayScreen, the puzzle board was represented indirectly through dictionaries of textures and scrambled pieces. The screen owned the tile arrangement, input queue, timing, movement rules, and drawing logic all in one place. The MonoGame port instead introduces a dedicated PuzzleBoard type that focuses only on board state and valid moves:

internal sealed class PuzzleBoard
{
    private readonly int[] tiles;

    public PuzzleBoard(int size = 4)
    {
        Size = size;
        tiles = new int[size * size];
        Reset();
    }

    public int Size { get; }
    public int BlankIndex { get; private set; }

    public void Shuffle(int moveCount, Random random)
    {
        Reset();
        var previousBlankIndex = -1;

        for (var move = 0; move < moveCount; move++)
        {
            var neighbors = GetNeighborIndexes(BlankIndex);
            if (previousBlankIndex >= 0 && neighbors.Count > 1)
            {
                neighbors.Remove(previousBlankIndex);
            }

            var nextBlankIndex = neighbors[random.Next(neighbors.Count)];
            previousBlankIndex = BlankIndex;
            Swap(BlankIndex, nextBlankIndex);
            BlankIndex = nextBlankIndex;
        }
    }
}

This is a much better shape for a long-lived codebase. The board can guarantee that shuffles stay solvable, validate restored state, and expose the current tile layout without knowing anything about textures, sprite batches, or screen transitions.

That small design change has a big effect. It makes the MonoGame GameplayScreen much easier to reason about because it no longer owns the game rules directly. Instead, it becomes the layer that translates keyboard and mouse input into board operations and then renders the current board state.

Reworking the UI for desktop input

The biggest behavioral difference between the original game and the port is not the puzzle itself. It is the environment around it.

The Windows Phone version naturally centered around phone-era assumptions. The MonoGame port had to feel good on a desktop with a mouse, a keyboard, a resizable window, and varying screen sizes. That shows up very clearly in the new menu infrastructure.

The base MenuScreen now understands keyboard navigation, Tab navigation, mouse wheel scrolling, hover selection, left click selection, and right click cancel behavior:

public override void HandleInput(InputState input)
{
    var hoveredEntryIndex = GetHoveredEntryIndex(input);
    if (hoveredEntryIndex.HasValue)
        selectedEntry = hoveredEntryIndex.Value;

    if (input.IsMenuUp(ControllingPlayer) || input.MouseWheelDelta >= 120)
        selectedEntry = (selectedEntry - 1 + menuEntries.Count) % menuEntries.Count;
    else if (input.IsMenuDown(ControllingPlayer) || input.MouseWheelDelta <= -120)
        selectedEntry = (selectedEntry + 1) % menuEntries.Count;

    if (input.IsMenuSelect(ControllingPlayer, out var playerIndex))
        OnSelectEntry(selectedEntry, playerIndex);
    else if (input.IsNewLeftClick(ControllingPlayer, out playerIndex)
          && hoveredEntryIndex.HasValue)
        OnSelectEntry(hoveredEntryIndex.Value, playerIndex);
    else if (input.IsNewRightClick(ControllingPlayer, out playerIndex))
        OnCancel(playerIndex);
}

That is a much better fit for a desktop game than a straight preservation of the old input model. The menu also scales itself based on viewport size, uses safe area calculations, and draws a proper desktop-style panel chrome rather than assuming a fixed phone screen.

The gameplay screen follows the same philosophy. It preserves the original controls, but widens them for desktop use:

public override void HandleInput(InputState input)
{
    if (input.IsPauseGame(ControllingPlayer))
    {
        ShowOptions(playerIndex);
        return;
    }

    if (input.IsNewKeyPress(Keys.R, ControllingPlayer, out _)
     || input.IsNewKeyPress(Keys.F5, ControllingPlayer, out _))
    {
        ScrambleBoard();
        return;
    }

    if (!input.IsNewLeftClick(ControllingPlayer, out _))
    {
        return;
    }

    if (TryMoveFromMouse(input.MousePosition))
    {
        moveCount++;
    }
}

On top of that, the port keeps the live preview mechanic from the old desktop build: holding Enter or F1 shows the solved image. That is a nice example of the project’s overall approach. The game did not need to become a different puzzle game. It just needed a better shell around the same core behavior.

Persistence without Windows Phone isolated storage

The original game persisted progress using IsolatedStorageFile and XML serialization. That made perfect sense on Windows Phone:

public static void Save(SaveState state)
{
    using (var userStore = IsolatedStorageFile.GetUserStoreForApplication())
    {
        if (userStore.FileExists(FILENAME))
            userStore.DeleteFile(FILENAME);

        using (var stream = new IsolatedStorageFileStream(FILENAME, FileMode.OpenOrCreate, userStore))
        {
            var serializer = new XmlSerializer(typeof(SaveState));
            serializer.Serialize(stream, state);
        }
    }
}

The MonoGame port keeps the resume-on-exit experience, but modernizes the implementation. Instead of serializing the entire screen stack, it persists the active gameplay state to %LocalAppData%, writes a simple versioned binary header, and uses a temporary file before replacing the real save file:

using (var stream = File.Open(
    temporarySaveFilePath,
    FileMode.Create,
    FileAccess.Write,
    FileShare.None))
{
    WriteSaveFileHeader(stream);
    gameplayScreen.Serialize(stream);
}

File.Move(temporarySaveFilePath, saveFilePath, overwrite: true);

I like this design a lot more than the original one.

It is explicit about what gets saved, it is versioned, it validates the header before restoring, and it cleans up corrupted save artifacts when loading fails. The GameplayScreen also tracks which flow was active when the game exited, so it can resume not just the board state but also whether the player was in the pause/options flow or the win flow.

That is a great example of a rewrite preserving behavior while still making the implementation significantly better.

Using GitHub Copilot CLI and Squad to do the rewrite

The most interesting part of this project was not MonoGame itself. It was the process.

This entire port was built through agentic engineering with GitHub Copilot CLI and Squad. The MonoGame repository is not just source code. It also contains the team structure and working agreements used to build it.

The primary implementation team is described directly in .squad/team.md:

| Name    | Role         |
| ------- | ------------ |
| Keaton  | Lead         |
| McManus | Gameplay Dev |
| Fenster | Platform Dev |
| Hockney | UI Dev       |
| Redfoot | Tester       |

And the decision log captured the working style explicitly:

### 2026-03-24: Preserve progress with small logical commits

**What:** During implementation, commit frequently in small, coherent groups so the repo keeps a detailed progress history.
**Why:** Incremental MonoGame porting will be easier to review, debug, and compare against the original XNA game when each change stays tightly scoped.

That matters because this was not a one-shot “translate this file” exercise. The agents had to:

study the original XNA repository
preserve the gameplay and screen flow
choose modern .NET and MonoGame project structure
adapt the UI to desktop input
rebuild persistence for a different platform
keep the work organized in small, reviewable commits

This is exactly the kind of task where agentic engineering shines.

There is a clear goal, a concrete reference implementation, and a bounded feature set. The old repository provides behavior and assets. The new repository provides the target platform and room for structural improvement. That combination lets agents do much more than boilerplate generation. They can reason about equivalence, identify where a literal port would be awkward, and reshape the code into something that fits the modern platform better.

In other words, the prompt was small, but the context was rich.

What stayed the same

Although the implementation changed a lot, the identity of the game did not.

The MonoGame port keeps the parts that made the original game feel like Chris’ Puzzle Game:

the same 4x4 sliding tile puzzle format
the same set of sample puzzle images
the same main menu to gameplay to completion flow
the same quick preview mechanic
the same reshuffle behavior
the same ability to resume progress on the next launch

What changed was everything around those core behaviors. The code is cleaner, the persistence story is stronger, the UI is more natural on a desktop, and the project can be built and maintained with modern tooling.

That is the best kind of rewrite. The spirit stays the same while the codebase stops fighting the platform.

Why MonoGame?

MonoGame is a very natural destination for old XNA projects. The conceptual model is close enough that the original structure still makes sense, but the tooling and runtime are current enough that the project can live comfortably in a modern .NET ecosystem.

For this game, MonoGame was exactly the right level of change.

I did not need a full engine migration to Unity or Godot. I did not need to reinvent the gameplay loop. I just needed a runtime and framework that still respected the XNA way of building games while letting the code run on current Windows and current .NET.

That made it possible to focus the rewrite on the places where modernization actually mattered: board logic, input handling, persistence, windowing, and project structure.

Final thoughts

Reviving an old XNA game this way was a lot of fun, but it was also a very practical demonstration of how useful agentic engineering has become.

This was not just “AI wrote some helper methods.” The agents were able to use the old repository as a reference, preserve the important gameplay behavior, improve the internal design, and ship a modern MonoGame port that still feels like the same game.

That is a very different experience from the old chat-driven copy/paste workflow. It feels much closer to delegation: define the outcome, provide the reference implementation, set constraints, and let the agents work through the migration.

If you want to compare the two versions yourself, the original XNA source code is here:

https://github.com/christianhelle/xnapuzzlegame

And the MonoGame port is here:

https://github.com/christianhelle/puzzlegame-mono

For me, this project was a nice reminder that old software does not always need to stay old. Sometimes all it needs is a modern framework, a good reference codebase, and an agent team that knows how to carry the intent forward.

From AI-Assisted Code Completion to Agentic Software Engineering

2026-03-17T00:00:00+00:00

Around four years ago, when GitHub Copilot was still in the early beta days, I tried AI-assisted code completion for the first time. Like most developers, I was equal parts skeptical and curious. The experience felt a little surreal. I would start writing a function, pause for a second, and the editor would continue the thought for me.

At first, it felt like a novelty. Then it became useful. Then it became part of my workflow. Somewhere along the way, Copilot stopped being something I occasionally experimented with and became a tool I use every single day. Today it is one of those tools I genuinely do not want to work without.

This post is about that journey: from AI-assisted code completion, to what now is a completely different mode of working altogether - agentic software engineering.

From novelty to daily habit

The first value I got from Copilot was obvious: it removed repetition. It filled in boilerplate, guessed tests, completed common patterns, and saved me from typing the same kinds of code over and over again. That alone was enough to make it useful.

But what made it stick was not just speed. It was momentum.

When the tool is good, you stay in flow longer. You spend less time context switching, less time writing scaffolding, and more time thinking about the parts that actually matter. Over time, Copilot started helping me with much more than method bodies. It became useful for tests, documentation, scripts, CI workflows, refactorings, and all the little pieces of engineering work that surround the code itself.

That is when it stopped feeling like autocomplete and started feeling like a real development companion.

Why I hated chat-driven development

There was, however, an awkward phase in the middle of all this: chat-driven development.

To be blunt, I hated it.

I thought it was an utter waste of time. The context switching was awful. I had to stop what I was doing, leave the editor mentally, explain the problem in a chat box, wait for a wall of text, copy pieces back into my code, discover that the result only half-fit the codebase, and then repair the damage manually. It felt like taking the most direct activity in software development - writing and changing code - and routing it through the slowest interface imaginable.

The results were often worse than the process. A lot of it felt verbose, vague, and overconfident. Chat-driven development had a habit of producing answers that looked finished from a distance and fell apart the moment they touched a real codebase. It was like programming by office memo.

At its worst, it felt like a workflow designed for people who wanted to describe software rather than build it. Too much prompting, too much pasting, too much ceremony, and far too little engineering. Instead of accelerating flow, it shattered flow. Instead of reducing cognitive load, it added another layer of it.

That is why I never saw chat-driven development as the future. For me, it was a clumsy transitional phase between code completion and something much more useful. The breakthrough was not “chat more.” The breakthrough was getting to a point where the system could actually do meaningful work with the right context, constraints, and autonomy.

Copilot Agent Mode with Claude Sonnet changed the game

For me, one of the biggest shifts happened when Claude Sonnet entered the picture. At first it was OK good, but far from impressive. Then it got better. Then it got much better. The jump from Claude Sonnet 3.5 to 4.0 was especially significant. It was both impressive and cost-effective. Suddenly, I can delegate large complex tasks to coding agents working in the background while I focus on something else. It can go and work by itself until the task is completed, no matter how long it took, and it would only cost me a single premium request.

The jump was hard to ignore. Prompts that previously produced a rough draft started producing something much closer to what I actually wanted. Multi-file edits became more coherent. Refactorings held together better. The model was much better at preserving intent across a larger body of work, which meant I could trust it with tasks that were broader than just completing the next few lines.

That was the moment where everything started improving rapidly.

A tiny prompt can still go a long way

One of my favorite things about this new way of working is that even very small prompts can produce surprisingly meaningful results.

For example, I gave a very simple instruction to improve the output of Refitter:

Make the output of Refitter look more fancy

That is not a detailed specification. It is barely even a design brief. But it was enough to move the tool from a simple output format to something much more polished.

Before:

After:

This is a good example of why I no longer think about these tools only in terms of productivity. The real value is experimentation and leverage. A short prompt can unlock a useful improvement that would otherwise require a lot of manual iteration, especially when the agent has enough context to understand the existing codebase and the kind of result you are aiming for. It takes no time for the agent to come up with the solution and if I don’t like it, I’ll just throw it away. I can also go more specific into asking it to try it out multiple approaches to a problem using different models.

From assistant to agent

AI-assisted development was already helpful, but it still often felt like a smart pair programmer that needed a lot of steering. With Sonnet or Opus, the output started feeling more deliberate. The reasoning got better. The edits became more consistent. The amount of useful work I could delegate increased noticeably.

That change matters because it pushed the experience beyond code completion. Once the model became strong enough to reason through larger changes, the natural next step was to let it take on broader responsibilities.

That broader responsibility is what I now think of as agentic engineering.

Traditional AI-assisted coding starts with the line, the method, or maybe the file. Agentic engineering starts with intent. You describe the outcome you want, give the system enough context and constraints, and let it execute a meaningful chunk of work with some level of autonomy.

This is where GitHub Copilot feels fundamentally different today than it did in the early beta days. It is still great at helping me write code, but it can also help me plan work, break it down, coordinate it, and execute it across a much larger surface area.

Running agents in parallel with /fleet

One of the features that makes this practical is /fleet in GitHub Copilot CLI.

/fleet takes a larger request or implementation plan, breaks it into smaller subtasks, and lets Copilot execute those subtasks in parallel when possible. The main agent acts as the orchestrator, manages dependencies, and delegates work to subagents. Each subagent gets its own context window, separate from the main agent and from the other subagents.

That separation is a big deal.

One giant chat thread is not a team. A team needs boundaries, focus, and clear handoffs. Parallel subagents with isolated context get much closer to that model than a single long-running conversation ever could.

Not every task benefits from parallelism, of course. Some work is inherently sequential. But when a problem can be decomposed into independent streams of work, /fleet is one of the most compelling tools in the current GitHub Copilot experience.

Building a persistent team with Squad

That brings me to Squad.

Squad gives you an AI development team through GitHub Copilot. You describe what you are building, and you get a team of specialists - frontend, backend, tester, lead - that live in your repo as files. They persist across sessions, learn your codebase, share decisions, and get better the more you use them.

It is not a chatbot wearing hats.

Each team member runs in its own context, reads only its own knowledge, and writes back what it learned. In practice, that means the team can have a roster, routing rules, agent charters, and shared decision logs inside the repository. The repo becomes the memory. The agents do not just respond in the moment - they accumulate working knowledge over time.

That is what makes the experience feel like a team rather than a clever prompt.

If I want a setup like this to work well, I have found that a few things matter:

Give each agent a clear specialty and boundaries.
Store team knowledge in the repository, not only in the chat transcript.
Use a lead or coordinator to route work and enforce handoffs.
Start downstream work early when it can happen independently.
Use /fleet when the plan can genuinely be parallelized.

When those pieces are in place, the interaction model changes completely. You stop thinking in terms of “help me write this file” and start thinking in terms of “here is the problem, here are the constraints, now go work as a team.”

Fixing Refitter issues hands-free with YOLO mode

The biggest example of this shift for me was when I put my agent team to work on Refitter.

Refitter has gained quite a bit of traction over the past couple of years, and with that came a growing issue backlog. Like many maintainers, I had collected more issues than I realistically had time to work through myself. So instead of picking them off one by one, I gave the team a larger objective and let it run.

This was the exact prompt:

Team, this project has gotten quite some traction over these past 2 years.
I have collected quite the number of issues that I simply don't have time to fix myself.
My issue list is publicly available on the Github repo: christianhelle/refitter.
Fix all the issues.
Apply fixes in individual feature branches and don't do all the work in a single branch

That one prompt resulted in a 29-hour session where 24 issues were resolved completely hands-free with the help of autopilot mode.

What I find especially interesting is not just the number of issues resolved, but the operating model behind it. The instruction to use individual feature branches forced the work to be broken apart instead of collapsing into one giant change. Combined with parallel agent execution, that starts to look much less like code completion and much more like coordinated engineering work.

That would have been almost impossible to imagine when I first tried Copilot in the beta days. Back then, the magic was that it could finish a line or sketch out a function. Now I can hand a team of agents a backlog and constraints, let them work through it for more than a day, and come back to real progress.

Where I am now

I still care deeply about writing code by hand. Code is the best and clearest way for me to express myself. I still love code completion and it is still the fastest interface between an idea in my head and code in my editor. GitHub Copilot remains a core part of my daily workflow for exactly that reason.

But the bigger story is what happened next.

The evolution from code completion to stronger reasoning, the arrival of models like Claude Opus, the ability to run work in parallel with /fleet, and the emergence of persistent repo-native agent teams like Squad have all pushed software development into a very different place.

I no longer think about AI as just something that helps me write code faster. I think about it as a system for delegating engineering work, coordinating specialists, and scaling execution without losing context.

That is why this feels like more than better autocomplete.

It feels like an entirely new form of software engineering. Agentic software engineering.

This shift has impacted how I build tools like Refitter, HTTP File Generator, and the various Zig and Rust projects on my projects page.

Generate a Changelog from GitHub Actions

2026-03-14T00:00:00+00:00

I recently built a GitHub Action that automatically generates changelogs from repository releases and merged pull requests. The action wraps chlogr, a fast changelog generator written in Zig that I created to simplify keeping changelogs up-to-date in my projects.

The Changelog Generator Action is published to the GitHub Marketplace and can generate changelogs for any repository, not just the one where the workflow runs. This makes it useful for monorepos, documentation sites, or projects that need to aggregate changelogs from multiple sources.

I built this because manually maintaining CHANGELOG.md files is tedious and error-prone. Tools that generate changelogs from commit messages often produce noisy output with implementation details rather than user-facing changes. By generating changelogs from GitHub releases and merged pull requests, the tool produces cleaner, more meaningful changelogs that focus on what matters to users.

What is chlogr?

chlogr is the underlying CLI tool that powers the GitHub Action. It’s written in Zig, compiles to a single native binary with zero dependencies, and is designed to be fast and simple.

The tool fetches GitHub releases and merged pull requests from the GitHub API, categorizes them by labels, and generates a Markdown changelog. It supports filtering by tag ranges, excluding specific labels, and handles GitHub authentication through multiple methods.

Key features include:

Fast and lightweight: Native binary, pure Zig standard library, no external dependencies
Smart categorization: Groups changes by labels (Features, Bug Fixes, Other)
Automatic linking: Generates links to PRs, issues, and contributors
Flexible authentication: Supports --token flag, environment variables, or gh CLI
Tag range filtering: Generate changelogs for specific release windows
Cross-platform: Works on Linux, macOS, and Windows

The tool is available on GitHub at https://github.com/christianhelle/chlogr.

What is the Changelog Generator Action?

The Changelog Generator Action is a reusable GitHub Action that wraps chlogr for use in CI/CD workflows. It handles downloading the appropriate chlogr binary for the runner platform, passing credentials, and generating the changelog file.

The action provides a clean interface with inputs for repository selection, output file path, tag filtering, label exclusion, and version pinning. It outputs the path to the generated file and a flag indicating whether the content changed, making it easy to conditionally commit the changelog.

Since it’s published to the GitHub Marketplace, you can reference it directly in your workflows without downloading or compiling anything.

Basic Usage

The simplest use case is generating a CHANGELOG.md file for the current repository. This workflow runs on every push to the main branch and on manual dispatch:

name: Changelog

on:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: write
  pull-requests: read
  issues: read

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Generate changelog
        id: changelog
        uses: christianhelle/changelog-generator-action@v1
        with:
          output: CHANGELOG.md

      - name: Commit changelog
        if: steps.changelog.outputs.changed == 'true'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add CHANGELOG.md
          git commit -m "Update changelog [skip ci]"
          git push

This workflow demonstrates the complete lifecycle: checkout, generate, and commit. The action uses the default $ for authentication and the current repository ($) as the target.

Understanding the Permissions

The permissions block is critical. The workflow needs:

contents: write - To commit the generated changelog back to the repository
pull-requests: read - To fetch merged pull request data from the GitHub API
issues: read - To access issue metadata referenced in pull requests

If you’re only generating the changelog without committing it (for example, uploading it as an artifact), you can remove the write permission.

Conditional Commit with the `changed` Output

The action outputs a changed flag that indicates whether the generated changelog differs from the existing file. This prevents empty commits when nothing has changed:

- name: Commit changelog
  if: steps.changelog.outputs.changed == 'true'
  run: |
    git add CHANGELOG.md
    git commit -m "Update changelog [skip ci]"
    git push

The [skip ci] suffix in the commit message prevents triggering the workflow again, avoiding an infinite loop.

Advanced Usage Examples

The action supports several advanced scenarios through its inputs. Let me walk through the most useful patterns.

Generating Changelog for a Different Repository

You can generate changelogs for any repository, not just the one where the workflow runs. This is useful for documentation sites or aggregation workflows:

- name: Generate changelog for Refitter
  uses: christianhelle/changelog-generator-action@v1
  with:
    repo: christianhelle/refitter
    output: artifacts/REFITTER_CHANGELOG.md

If the target repository is private, you’ll need to provide a Personal Access Token (PAT) with appropriate permissions:

- name: Generate changelog for private repo
  uses: christianhelle/changelog-generator-action@v1
  with:
    repo: myorg/private-repo
    github-token: $
    output: CHANGELOG.md

Filtering by Tag Range

You can limit the changelog to a specific release window using since-tag and until-tag:

- name: Generate changelog for v1.10.0 to v1.11.0
  uses: christianhelle/changelog-generator-action@v1
  with:
    since-tag: v1.10.0
    until-tag: v1.11.0
    output: CHANGELOG-1.11.0.md

This is particularly useful when generating release-specific changelogs or when you want to document changes between two specific versions.

Excluding Labels

Some pull requests shouldn’t appear in the changelog—duplicates, won’t-fix issues, or internal refactoring. Exclude them by label:

- name: Generate changelog without noise
  uses: christianhelle/changelog-generator-action@v1
  with:
    exclude-labels: duplicate,wontfix,internal,dependencies
    output: CHANGELOG.md

Any pull request tagged with these labels will be filtered out of the generated changelog.

Pinning chlogr Version

For deterministic builds, pin the chlogr version rather than using latest:

- name: Generate changelog with pinned version
  uses: christianhelle/changelog-generator-action@v1
  with:
    chlogr-version: 0.1.2
    output: CHANGELOG.md

This ensures the changelog format and behavior remain consistent across workflow runs, even when new chlogr versions are released.

Multiple Changelogs in One Workflow

You can generate multiple changelogs in a single workflow by calling the action multiple times:

- name: Generate main project changelog
  uses: christianhelle/changelog-generator-action@v1
  with:
    output: CHANGELOG.md

- name: Generate changelog for last release only
  uses: christianhelle/changelog-generator-action@v1
  with:
    since-tag: v1.0.0
    output: CHANGELOG-LATEST.md

This is useful for creating both a complete historical changelog and a focused release-specific version.

Real-World Example: Argiope

I use this action in my Argiope project, a web crawler for broken link detection. The workflow is simple but effective:

name: Changelog

on:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: write
  pull-requests: read
  issues: read

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Generate changelog
        id: changelog
        uses: christianhelle/changelog-generator-action@v1
        with:
          output: CHANGELOG.md

      - name: Commit changelog
        if: steps.changelog.outputs.changed == 'true'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add CHANGELOG.md
          git commit -m "Update changelog [skip ci]"
          git push

This workflow runs automatically on every push to main and can be manually triggered via workflow_dispatch. It keeps the changelog synchronized with the latest releases without any manual intervention.

The benefits for Argiope include:

No manual maintenance: Changelog updates automatically when I create releases
Clean git history: The changelog commit uses the GitHub Actions bot identity
No infinite loops: The [skip ci] commit message prevents re-triggering
Always accurate: The changelog reflects actual releases and merged PRs, not commit messages

Integration Patterns

Here are some common patterns for integrating changelog generation into your CI/CD workflows.

Generate Changelog on Release

Trigger changelog generation when you create a new release:

name: Release Changelog

on:
  release:
    types: [published]

permissions:
  contents: write
  pull-requests: read
  issues: read

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate changelog
        uses: christianhelle/changelog-generator-action@v1
        with:
          output: CHANGELOG.md

      - name: Commit and push
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add CHANGELOG.md
          git commit -m "Update changelog for $ [skip ci]"
          git push

This ensures the changelog is updated immediately after every release.

Upload Changelog as Release Asset

Instead of committing the changelog, attach it to the release:

- name: Generate changelog
  uses: christianhelle/changelog-generator-action@v1
  with:
    output: CHANGELOG.md

- name: Upload changelog to release
  uses: softprops/action-gh-release@v1
  with:
    files: CHANGELOG.md

This makes the changelog available as a downloadable artifact on the release page.

Scheduled Changelog Updates

Run changelog generation on a schedule to keep it up-to-date even without explicit releases:

on:
  schedule:
    - cron: "0 0 * * 0" # Weekly on Sunday at midnight
  workflow_dispatch:

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate changelog
        uses: christianhelle/changelog-generator-action@v1
        with:
          output: CHANGELOG.md

      - name: Create pull request
        uses: peter-evans/create-pull-request@v5
        with:
          commit-message: Update changelog
          title: "chore: update changelog"
          branch: changelog-update

This creates a pull request with the updated changelog rather than committing directly, allowing you to review changes before merging.

Multi-Platform Matrix Build

The action supports all major platforms and architectures:

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]

runs-on: $

steps:
  - uses: actions/checkout@v4

  - name: Generate changelog
    uses: christianhelle/changelog-generator-action@v1
    with:
      output: CHANGELOG.md

The action automatically detects the runner platform and downloads the appropriate chlogr binary (Linux x64/arm64, macOS x64/arm64, Windows x64).

Features and Capabilities

Let me dive deeper into how the action categorizes and formats changelog entries.

Label Categorization

The action groups changelog entries into three categories based on pull request labels:

Features: PRs with labels like enhancement, feature, or new-feature
Bug Fixes: PRs with labels like bug, bugfix, or fix
Other: Everything else

This produces clean, scannable changelog sections:

# Changelog

## [v1.2.0](https://github.com/owner/repo/releases/tag/v1.2.0) - 2024-01-15

### Features

- Add new feature X (#123) (@alice)

### Bug Fixes

- Fix critical bug (#124) (@bob)

### Other

- Update documentation (#125) (@charlie)

The categorization happens automatically based on the labels assigned to pull requests. For best results, establish a labeling convention in your repository.

Link Generation

The generated changelog includes links to:

Release tags: Each version header links to the GitHub release page
Pull requests: PR numbers link to the PR page
Contributors: Author usernames link to their GitHub profiles

This makes the changelog a navigable reference rather than just a text document.

Token Resolution Strategies

The action handles GitHub authentication through a flexible fallback chain. When you don’t specify github-token, it uses the default workflow token ($). When generating changelogs for the current repository, this is usually sufficient.

For cross-repository changelog generation, the action respects the token you provide:

- name: Generate changelog
  uses: christianhelle/changelog-generator-action@v1
  with:
    repo: otherorg/otherrepo
    github-token: $

The underlying chlogr tool has even more fallback options (environment variables, gh CLI), but the action normalizes this by passing the token explicitly.

Output File Handling

The action handles both absolute and relative paths for the output file. Relative paths are resolved from the GITHUB_WORKSPACE directory:

# Writes to $GITHUB_WORKSPACE/CHANGELOG.md
- uses: christianhelle/changelog-generator-action@v1
  with:
    output: CHANGELOG.md

# Writes to $GITHUB_WORKSPACE/docs/CHANGELOG.md
- uses: christianhelle/changelog-generator-action@v1
  with:
    output: docs/CHANGELOG.md

# Writes to an absolute path
- uses: christianhelle/changelog-generator-action@v1
  with:
    output: /tmp/CHANGELOG.md

The action outputs the absolute path via changelog-path, which you can reference in subsequent steps:

- name: Generate changelog
  id: gen
  uses: christianhelle/changelog-generator-action@v1

- name: Print path
  run: echo "Changelog written to $"

Troubleshooting and Tips

Here are some common issues and solutions when using the action.

Token Authentication Errors

If you see 401 Unauthorized or 403 Forbidden errors, check your permissions:

permissions:
  contents: read
  pull-requests: read
  issues: read

For private repositories or cross-repository access, use a PAT:

- uses: christianhelle/changelog-generator-action@v1
  with:
    github-token: $

The PAT needs the repo scope for private repositories or public_repo for public ones.

Rate Limiting

The GitHub API has rate limits (5,000 requests/hour for authenticated requests, 60/hour for unauthenticated). The action uses authenticated requests via the workflow token, so rate limiting is rarely an issue.

If you do hit rate limits (typically in very large repositories or when running many workflows simultaneously), you’ll see a 429 Too Many Requests error. The solution is to wait and retry, or reduce the frequency of changelog generation.

Empty or Missing Changelogs

If the generated changelog is empty or missing expected entries, verify:

The repository has GitHub releases: The tool fetches releases via the GitHub Releases API, not just tags
Pull requests are merged: Only merged PRs appear in the changelog
Tag filtering is correct: If using since-tag or until-tag, ensure the tags exist

You can test the underlying chlogr tool locally to debug issues:

# Download chlogr
curl -L https://github.com/christianhelle/chlogr/releases/latest/download/chlogr-linux-x86_64 -o chlogr
chmod +x chlogr

# Generate changelog
./chlogr --repo owner/repo --token $GITHUB_TOKEN --output CHANGELOG.md

Platform and Architecture Support

The action supports:

Linux: x64, arm64
macOS: x64, arm64
Windows: x64

If you use a runner platform that doesn’t match these, the action will fail with a clear error message. Self-hosted runners should use one of these supported platforms.

Permissions for Committing

If your workflow commits the changelog and you see errors like unable to access, ensure:

The workflow has contents: write permission
Your repository settings allow GitHub Actions to create and approve pull requests (Settings → Actions → General → Workflow permissions)

For repositories with branch protection rules, you may need to use a PAT with elevated permissions or create a pull request instead of committing directly.

Version Pinning Best Practices

For production workflows, pin both the action version and the chlogr version:

- uses: christianhelle/changelog-generator-action@v1.0.3
  with:
    chlogr-version: 0.1.2

This prevents unexpected changes when either the action or chlogr is updated. Use Dependabot or Renovate to keep versions up-to-date.

Conclusion

Automating changelog generation from GitHub Actions eliminates manual maintenance while producing cleaner, more meaningful changelogs than commit-based approaches. The Changelog Generator Action makes this easy to integrate into any workflow, whether you’re generating changelogs for the current repository, multiple repositories, or specific release windows.

The action is published to the GitHub Marketplace at https://github.com/marketplace/actions/generate-changelog-with-chlogr, and the underlying chlogr tool is available at https://github.com/christianhelle/chlogr.

If you’re looking for a simple way to keep your changelogs up-to-date, give it a try. It takes just a few lines of YAML to set up and runs in seconds.

ZigFaker - A Zig library to minimize unit testing ceremony

2026-03-08T00:00:00+00:00

Back in 2022, I created a project called AutoFaker, a Python library designed to minimize the setup and arrange phase of unit tests. Coming from a C# background, I really missed tools like AutoFixture and decided to build something similar for my Python projects.

Fast forward to today, and I find myself diving deep into a new language: Zig. As part of my learning journey, I wanted a substantial project to sink my teeth into. If I’m to be completely honest, this project came to life simply because I wanted to write something non-trivial in Zig, and not necessarily because there is a burning need for such a tool in the Zig ecosystem right now. However, it served as a fantastic learning exercise to explore Zig’s powerful memory management and its incredible comptime type reflection capabilities.

The result of this exercise is ZigFaker, the Zig version of my AutoFaker library, designed to make it significantly easier to write unit tests by reducing boilerplate setup.

When writing unit tests, you normally start by creating objects that represent the initial state of the test. This phase is called the arrange or setup phase. In most cases, the system you want to test will force you to specify much more information than you really care about, so you frequently end up creating objects with no influence on the test itself, just to satisfy the compiler.

ZigFaker helps by generating such anonymous or fake data for you automatically.

Installation

ZigFaker is built for Zig 0.15.0 or later. To use it in your project, add it to your build.zig.zon dependencies by fetching the archive:

zig fetch --save https://github.com/christianhelle/zigfaker/archive/refs/heads/main.tar.gz

Then, in your build.zig, add the module to your test step:

const zigfaker_dep = b.dependency("zigfaker", .{
    .target = target,
    .optimize = optimize,
});
const zigfaker_mod = zigfaker_dep.module("zigfaker");

// Add to your test executable:
exe_tests.root_module.addImport("zigfaker", zigfaker_mod);

Supported Data Types

Leveraging Zig’s comptime, ZigFaker recursively inspects your types and populates them. Currently, it supports creating anonymous variables for:

Primitives: i8 through i64, u8 through u64, f32, f64, and bool
Strings: []const u8 (Generates UUID-like strings or contextual fake data)
Structs: Fully recursive population, including nested structs
Optionals: ?T (Randomly evaluates to null or a generated T)
Enums: Randomly selects a valid variant
Arrays: [N]T fills all elements

Example Usages

To use ZigFaker, you simply initialize it with an allocator. Because it needs to generate dynamic strings, it uses an ArenaAllocator under the hood to make cleanup a breeze when deinit() is called.

Anonymous Primitive Types

Creating basic built-in types is straightforward:

const std = @import("std");
const zigfaker = @import("zigfaker");

test "create anonymous primitives" {
    var faker = zigfaker.ZigFaker.init(std.testing.allocator);
    defer faker.deinit();

    const id     = try faker.create(i32);     // e.g. 1453820643
    const score  = try faker.create(f64);     // e.g. 812345.67
    const active = try faker.create(bool);    // e.g. true
    const token  = try faker.create([]const u8); // e.g. "a3f1b2c4-9e8d-7f6a-5b4c-3d2e1f0a9b8c"
}

Anonymous Structs

The real power of ZigFaker comes when you need to populate entire structs. You don’t need to specify anything about the struct’s internals; ZigFaker figures it out at compile time.

const User = struct {
    id: i32,
    score: f64,
    active: bool,
};

test "create anonymous struct" {
    var faker = zigfaker.ZigFaker.init(std.testing.allocator);
    defer faker.deinit();

    const user = try faker.create(User);
    // user.id, user.score, and user.active are all populated with random values
}

Creating Collections

If you need a list of dummy data, createMany has you covered. The resulting slice is owned by the ZigFaker arena, so you don’t need to free it manually.

test "create multiple users" {
    var faker = zigfaker.ZigFaker.init(std.testing.allocator);
    defer faker.deinit();

    const users = try faker.createMany(User, 3);
    // users is a []User with 3 elements, all automatically populated
}

Realistic Fake Data

There are times when completely random, anonymous UUID-like strings don’t make much sense—especially in data-centric scenarios or integration tests where you might want to look at the data being passed around.

ZigFaker handles this gracefully. By initializing it with initWithFakeData, it looks at your struct’s field names (e.g., first_name, email, ipv4) and generates contextually appropriate string data.

const Person = struct {
    id: i32,
    first_name: []const u8,
    last_name: []const u8,
    job: []const u8,
    email: []const u8,
    city: []const u8,
    country: []const u8,
    ipv4: []const u8,
    ipv6: []const u8,
    hostname: []const u8,
    currency_name: []const u8,
    currency_code: []const u8,
};

test "create realistic fake data" {
    var faker = zigfaker.ZigFaker.initWithFakeData(std.testing.allocator);
    defer faker.deinit();

    const person = try faker.create(Person);

    // person.first_name => "Jennifer"
    // person.last_name  => "Martinez"
    // person.job        => "Cloud Architect"
    // person.email      => "jenniferw42@gmail.com"
    // person.city       => "San Francisco"
    // person.country    => "Germany"
    // person.ipv4       => "192.168.24.100"
    // person.ipv6       => "8f3c:0a2b:4d1e:7f9c:1b2a:3e4d:5f6c:7a8b"
    // person.hostname   => "api12.smith.io"
}

Nested Structs

The comptime reflection naturally extends to nested structures without any additional configuration.

const Address = struct {
    street: []const u8,
    city: []const u8,
    country: []const u8,
};

const Employee = struct {
    id: i32,
    first_name: []const u8,
    last_name: []const u8,
    job: []const u8,
    address: Address,
};

test "create nested struct" {
    var faker = zigfaker.ZigFaker.initWithFakeData(std.testing.allocator);
    defer faker.deinit();

    const emp = try faker.create(Employee);
    // emp.address.city => "Los Angeles"
    // emp.address.country => "Canada"
}

Enums and Optionals

Handling variants and nullable types is baked right in:

const Status = enum { pending, active, suspended, closed };

test "enums and optionals" {
    var faker = zigfaker.ZigFaker.init(std.testing.allocator);
    defer faker.deinit();

    const status = try faker.create(Status); // Randomly picks one of the four variants
    const maybe_id = try faker.create(?i32); // Randomly evaluates to null or a valid i32
}

Reproducible Output

Finally, flaky unit tests are the absolute worst. If you need your randomly generated data to be deterministic across test runs, you can seed the generator:

test "seeded generation" {
    var faker = zigfaker.ZigFaker.initWithSeed(std.testing.allocator, 42);
    defer faker.deinit();

    const v1 = try faker.create(i32); // This will always generate the same value for seed 42
}

Building ZigFaker was an excellent crash course in Zig’s comptime reflection. While it might have started simply as an excuse to write more Zig code, I genuinely believe it can cut down on the boilerplate required for heavily data-driven tests in Zig.

You can check out the full source code and documentation on GitHub: christianhelle/zigfaker.

Building a web crawler and broken link detector in Zig

2026-03-05T00:00:00+00:00

I recently built a web crawler for broken link detection and image downloading in Zig. The tool can crawl websites, detect broken links, generate reports in multiple formats, and download images from web pages. I named it Argiope after the genus of orb-weaving spiders, which seemed fitting for a web crawler.

The source code is available on GitHub at https://github.com/christianhelle/argiope.

Like my previous Zig project, GitHub Copilot wrote most of the boilerplate, including the GitHub workflows, README, install scripts, and snapcraft.yaml file. The entire project took a few evenings to build.

How it works

The crawler uses a Breadth-first search (BFS) approach to traverse web pages. It starts with a seed URL, fetches the page, extracts all links, and adds them to a queue for processing. Each URL is normalized and checked against a visited set to avoid processing the same URL twice.

pub const Crawler = struct {
    allocator: std.mem.Allocator,
    base_url: []u8,
    base_host: []u8,
    queue: std.ArrayListUnmanaged(QueueEntry) = .empty,
    visited: std.StringHashMapUnmanaged(void) = .empty,
    results: std.ArrayListUnmanaged(CrawlResult) = .empty,
    options: CrawlOptions,

    pub fn init(allocator: std.mem.Allocator, url: []const u8, options: CrawlOptions) Crawler {
        const base_url = allocator.dupe(u8, url) catch "";
        const base_host = url_mod.extractHost(base_url) orelse "";
        return .{
            .allocator = allocator,
            .base_url = base_url,
            .base_host = base_host,
            .options = options,
        };
    }

    pub fn crawl(self: *Crawler) !void {
        try self.queue.append(self.allocator, .{
            .url = try self.allocator.dupe(u8, self.base_url),
            .depth = 0,
        });

        if (self.options.parallel) {
            try self.crawlParallel();
        } else {
            try self.crawlSequential();
        }
    }
};

The tool supports both sequential and parallel crawling. In parallel mode, a thread pool processes multiple URLs concurrently, which significantly speeds up crawling for sites with many links.

Domain restriction is enforced by extracting the host from each URL and comparing it to the base URL’s host. External links are still checked for broken status but not followed for further crawling. This keeps the crawler focused on the target site while still validating outbound links.

pub fn isInternal(self: *const Crawler, url: []const u8) bool {
    const host = url_mod.extractHost(url) orelse return false;
    return std.mem.eql(u8, host, self.base_host);
}

HTML Parsing

Rather than pulling in a full HTML parser dependency, I wrote a lightweight scanner that extracts links and image sources. It iterates through the HTML looking for opening tags and extracts href attributes from anchor tags and src attributes from image tags.

pub fn extractLinks(allocator: std.mem.Allocator, html: []const u8) ![]Link {
    var links: std.ArrayListUnmanaged(Link) = .empty;

    var pos: usize = 0;
    while (pos < html.len) {
        const tag_start = std.mem.indexOfPos(u8, html, pos, "<") orelse break;
        pos = tag_start + 1;
        if (pos >= html.len) break;

        // Skip comments
        if (pos + 2 < html.len and html[pos] == '!' and
            html[pos + 1] == '-' and html[pos + 2] == '-') {
            const comment_end = std.mem.indexOfPos(u8, html, pos, "-->") orelse break;
            pos = comment_end + 3;
            continue;
        }

        // Read tag name and extract attributes...
        const tag_name = html[tag_name_start..pos];

        // Determine what attribute we're looking for
        const attr_name: ?[]const u8 = blk: {
            if (asciiEqlIgnoreCase(tag_name, "a") or
                asciiEqlIgnoreCase(tag_name, "link") or
                asciiEqlIgnoreCase(tag_name, "area"))
            {
                break :blk "href";
            }
            if (asciiEqlIgnoreCase(tag_name, "img") or
                asciiEqlIgnoreCase(tag_name, "script") or
                asciiEqlIgnoreCase(tag_name, "source"))
            {
                break :blk "src";
            }
            break :blk null;
        };

        // Extract and store the attribute value...
    }

    return links.toOwnedSlice(allocator);
}

The scanner also handles srcset attributes on image tags, parsing the comma-separated list of image URLs. It skips JavaScript, mailto, tel, data URLs, and fragment-only links.

URL Normalization

URL handling is surprisingly complex. Relative URLs need to be resolved against the base URL, query parameters may need to be normalized, and trailing slashes should be handled consistently.

pub fn resolve(allocator: std.mem.Allocator, base: []const u8, href: []const u8) ![]u8 {
    // Absolute URL
    if (std.mem.indexOf(u8, href, "://") != null) {
        return allocator.dupe(u8, href);
    }

    // Protocol-relative URL
    if (std.mem.startsWith(u8, href, "//")) {
        const proto = extractProtocol(base) orelse "https";
        return std.fmt.allocPrint(allocator, "{s}:{s}", .{ proto, href });
    }

    // Absolute path
    if (href.len > 0 and href[0] == '/') {
        const origin = try extractOrigin(allocator, base);
        defer allocator.free(origin);
        return std.fmt.allocPrint(allocator, "{s}{s}", .{ origin, href });
    }

    // Relative path
    const base_dir = extractDirectory(base);
    return std.fmt.allocPrint(allocator, "{s}/{s}", .{ base_dir, href });
}

The normalize function ensures URLs are in a consistent form by converting to lowercase (for the scheme and host), removing default ports, and collapsing path segments.

HTTP Client

The tool uses Zig’s standard library HTTP client with custom timeout and redirect handling. Each request is wrapped with a timeout to avoid hanging on unresponsive servers.

pub const FetchOptions = struct {
    max_redirects: u8 = 5,
    timeout_ms: u32 = 10_000,
    max_body_size: usize = 10 * 1024 * 1024,
};

pub fn fetch(
    client: *std.http.Client,
    allocator: std.mem.Allocator,
    url: []const u8,
    options: FetchOptions,
) !FetchResult {
    const uri = try std.Uri.parse(url);

    var req = try client.open(.GET, uri, .{
        .server_header_buffer = try allocator.alloc(u8, 16384),
    });
    defer req.deinit();

    req.send() catch |err| {
        return FetchResult{
            .status = 0,
            .body = null,
            .error_msg = try allocator.dupe(u8, @errorName(err)),
        };
    };

    try req.wait();

    const status = @intFromEnum(req.response.status);

    // Handle redirects
    if (status >= 300 and status < 400 and options.max_redirects > 0) {
        const location = req.response.headers.getFirstValue("location") orelse {
            return error.InvalidRedirect;
        };
        // Follow redirect...
    }

    // Read response body...
    const body = try req.reader().readAllAlloc(allocator, options.max_body_size);

    return FetchResult{
        .status = @intCast(status),
        .body = body,
        .error_msg = null,
    };
}

The client handles HTTP redirects up to a configurable limit and collects both the status code and response body. Errors during the request are captured and returned as part of the result rather than propagated, allowing the crawler to continue processing other URLs.

Command Line Interface

The CLI supports two main commands: check for broken link detection and images for downloading images. Options include crawl depth, timeout, request delay, and output format.

pub const Command = enum {
    check,
    images,
    help,
    version_cmd,
};

pub const Options = struct {
    command: Command = .help,
    url: ?[]const u8 = null,
    depth: u16 = 3,
    timeout_ms: u32 = 10_000,
    delay_ms: u32 = 100,
    output_dir: []const u8 = "./download",
    verbose: bool = false,
    parallel: bool = false,
    report: ?[]const u8 = null,
    report_format: ReportFormat = .text,
    include_positives: bool = false,
};

pub fn parseArgs(args: []const []const u8) !Options {
    var opts = Options{};

    if (args.len < 2) return opts;

    var i: usize = 1;
    while (i < args.len) : (i += 1) {
        const arg = args[i];

        if (std.mem.eql(u8, arg, "check")) {
            opts.command = .check;
        } else if (std.mem.eql(u8, arg, "images")) {
            opts.command = .images;
        } else if (std.mem.startsWith(u8, arg, "--depth")) {
            // Parse depth value...
        } else if (std.mem.startsWith(u8, arg, "--timeout")) {
            // Parse timeout value...
        } else if (!std.mem.startsWith(u8, arg, "-")) {
            opts.url = arg;
        }
    }

    return opts;
}

The parser iterates through command-line arguments, identifying commands, flags, and values. It handles both short (-v) and long (--verbose) flag formats.

Report Generation

The tool generates reports in three formats: plain text, Markdown, and HTML. Reports can include just broken links or all checked URLs depending on the --include-positives flag.

pub fn write(
    allocator: std.mem.Allocator,
    path: []const u8,
    format: cli_mod.ReportFormat,
    url: []const u8,
    results: []const crawler_mod.CrawlResult,
    summary: summary_mod.CheckSummary,
    include_positives: bool,
) !void {
    const file = try std.fs.cwd().createFile(path, .{ .truncate = true });
    defer file.close();

    var buf: [65536]u8 = undefined;
    var fw = file.writer(&buf);
    const w = &fw.interface;

    switch (format) {
        .text => try writeText(w, url, results, summary, include_positives),
        .markdown => try writeMarkdown(w, url, results, summary, include_positives),
        .html => try writeHtml(allocator, w, url, results, summary, include_positives),
    }

    try w.flush();
}

The HTML report is self-contained with inline CSS and uses a card-based layout with color-coded status badges. This makes it suitable for embedding in CI/CD pipelines or sharing as a standalone file.

Usage

The basic usage is straightforward. Run argiope check <url> to scan a website for broken links:

$ argiope check https://christianhelle.com --depth 3

Crawling https://christianhelle.com (depth=3, timeout=10s)...

------------------------------------------------------------------------
Status   Type       Time(ms)   URL
------------------------------------------------------------------------
404      internal   45         https://christianhelle.com/missing-page
------------------------------------------------------------------------

Summary:
  Total URLs checked: 127
  OK:                 126
  Broken:             1
  Errors:             0
  Internal:           115
  External:           12

Timing:
  Total crawl time:   2345ms
  Avg response time:  18ms
  Min response time:  8ms
  Max response time:  156ms

For downloading images, use the images command:

$ argiope images https://example.com/gallery -o ./images

Downloading images from https://example.com/gallery...

Downloaded: page_1/image_1.jpg
Downloaded: page_1/image_2.jpg
Downloaded: page_2/image_1.png
...

Downloaded 42 images to ./images

Generate a report file instead of printing to the console:

argiope check https://christianhelle.com --report report.html --report-format html

argiope check https://christianhelle.com --report report.md --report-format markdown --include-positives

Use parallel crawling for faster processing on sites with many links:

argiope check https://christianhelle.com --parallel --depth 5

Distribution

Like my previous Zig project, I wanted simple distribution across platforms. GitHub Copilot generated the installation scripts and snapcraft configuration.

The install.sh script downloads the latest release for Linux or macOS:

#!/usr/bin/env bash
set -e

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)

case $ARCH in
    x86_64) ARCH="x86_64" ;;
    aarch64|arm64) ARCH="aarch64" ;;
    *) echo "Unsupported architecture: $ARCH"; exit 1 ;;
esac

case $OS in
    linux) PLATFORM="linux-$ARCH" ;;
    darwin) PLATFORM="macos-$ARCH" ;;
    *) echo "Unsupported OS: $OS"; exit 1 ;;
esac

URL="https://github.com/christianhelle/argiope/releases/latest/download/argiope-$PLATFORM"

curl -L "$URL" -o argiope
chmod +x argiope
sudo mv argiope /usr/local/bin/

echo "argiope installed successfully!"

For Windows users, install.ps1 does the same:

$ErrorActionPreference = "Stop"

$url = "https://github.com/christianhelle/argiope/releases/latest/download/argiope-windows-x86_64.exe"
$dest = "$env:USERPROFILE\bin\argiope.exe"

New-Item -ItemType Directory -Force -Path (Split-Path $dest) | Out-Null
Invoke-WebRequest -Uri $url -OutFile $dest

Write-Host "argiope installed to $dest"
Write-Host "Add $env:USERPROFILE\bin to your PATH if needed."

The snapcraft.yaml configuration allows publishing to the Snap Store:

name: argiope
base: core22
version: "0.1.0"
summary: A web crawler for broken-link detection
description: |
  A fast, multi-threaded web crawler that detects broken links,
  generates reports, and downloads images.
grade: stable
confinement: strict

apps:
  argiope:
    command: bin/argiope
    plugs:
      - network
      - home

The GitHub Actions workflow builds binaries for all platforms and attaches them to releases:

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            target: x86_64-linux
          - os: ubuntu-latest
            target: aarch64-linux
          - os: macos-latest
            target: x86_64-macos
          - os: macos-latest
            target: aarch64-macos
          - os: windows-latest
            target: x86_64-windows

Conclusion

Building Argiope was a great exercise in working with Zig’s standard library, particularly the HTTP client and file system APIs. The tool is fast, produces a single static binary with zero dependencies, and runs on Linux, macOS, and Windows.

If you need to check your website for broken links or download images from web pages, give Argiope a try. The source code is on GitHub at https://github.com/christianhelle/argiope.

Modernizing REST API Client Code Generator with the New Visual Studio Extensibility Model

2026-02-22T00:00:00+00:00

I recently rebuilt the REST API Client Code Generator extension for Visual Studio from the ground up using the new Visual Studio.Extensibility model. This migration allowed the extension to run out-of-process and leverage the full power of .NET 8.0. In this post, I’ll walk through the architectural changes, the challenges of the old model, and how the new extensibility API simplifies modern extension development.

The source code for the new extension is available on GitHub.

The Evolution of an Extension

The original version of this extension (source code available on GitHub) was built using the traditional Visual Studio SDK. It served its purpose well, but as with any software built on older frameworks, it began to show its age.

The “Dependency Hell” of In-Process Extensions

One of the most significant pain points with the old Visual Studio SDK is that extensions run in-process with Visual Studio. This means your extension shares the same memory space and dependencies as the IDE itself.

A classic example of this is Newtonsoft.Json. If your extension depends on version 13.0.1, but Visual Studio has loaded version 12.0.3 for its own internal use, you enter “Dependency Hell”. You’re forced to use binding redirects, assembly loading hacks, or simply hope for the best.

By moving to the new out-of-process extensibility model, the extension runs in its own isolated process. This architecture provides several key benefits:

True Isolation: The extension runs on .NET 8.0, completely independent of the .NET Framework 4.8 runtime that powers Visual Studio.
No More Binding Redirects: I can use any version of any library I want—including System.Text.Json or newer versions of Newtonsoft.Json—without clashing with Visual Studio’s dependencies.
Improved Stability: If the extension crashes, it doesn’t take down the entire IDE with it.

From “Custom Tools” to Explicit Commands

In the previous version, the extension relied on the Single File Generator (or “Custom Tool”) mechanism. This is a legacy feature where you select a file in Solution Explorer, go to the Properties window, and type a magic string like RefitterCodeGenerator into the “Custom Tool” field.

While this felt “integrated,” it had significant drawbacks:

Discoverability: Users had to know the magic string to type.
Silent Failures: If the generation failed, it was often difficult to see why without digging into the Output window.
Blocking the UI: The generation happened on the UI thread, freezing Visual Studio for large API specifications.

The new extension abandons this pattern in favor of explicit context menu commands. You now simply right-click an OpenAPI file and select “Generate Client Code”.

Architecture Comparison: Entry Points

The difference in how the extension is initialized is striking. The old model used the AsyncPackage class, decorated with a multitude of attributes to register menus, tool windows, and options pages.

Old VSPackage Entry Point - VsPackage.cs:

[Guid("47AFE4E1-5A52-4FE1-8CA7-EDB8310BDA4A")]
[ProvideMenuResource("Menus.ctmenu", 1)]
[ProvideUIContextRule(...)]
[ProvideOptionPage(typeof(GeneralOptionPage), VsixName, GeneralOptionPage.Name, 0, 0, true)]
public sealed class VsPackage : AsyncPackage
{
    private readonly ICommandInitializer[] commands = {
        new AutoRestCodeGeneratorCustomToolSetter(),
        new NSwagCodeGeneratorCustomToolSetter(),
        // ...
    };

    protected override async Task InitializeAsync(
        CancellationToken cancellationToken,
        IProgress<ServiceProgressData> progress)
    {
        await JoinableTaskFactory.SwitchToMainThreadAsync(cancellationToken);
        await base.InitializeAsync(cancellationToken, progress);

        foreach (var command in commands)
            await command.InitializeAsync(this, cancellationToken);
    }
}

The new model uses a cleaner, more modern approach. The entry point inherits from Extension, and we use Dependency Injection right out of the box.

New Extension Entry Point - ExtensionEntrypoint.cs:

[VisualStudioContribution]
internal class ExtensionEntrypoint : Extension
{
    public override ExtensionConfiguration ExtensionConfiguration => new()
    {
        Metadata = new(
            id: "f7530eb1-1ce9-46ac-8fab-165b68cf3d61",
            version: ExtensionAssemblyVersion,
            displayName: "REST API Client Code Generator (PREVIEW)",
            description: "Generate REST API client code from OpenAPI/Swagger specifications")
    };

    [VisualStudioContribution]
    public static MenuConfiguration GenerateMenu => new("%ApiClientCodeGenerator.GroupDisplayName%")
    {
        Placements = [KnownPlacements.ItemNode],
        Children = [
            MenuChild.Command<Commands.GenerateRefitterCommand>(),
            MenuChild.Command<Commands.GenerateNSwagCommand>(),
            // ...
        ],
    };

    protected override void InitializeServices(IServiceCollection serviceCollection)
    {
        serviceCollection.AddSingleton<ExtensionSettingsProvider>();
        base.InitializeServices(serviceCollection);
    }
}

Notice how we can register services like ExtensionSettingsProvider using standard .NET dependency injection patterns (InitializeServices).

Modernizing Commands and Async Execution

One of the biggest improvements in the new model is that everything is async by default. In the old SDK, you had to carefully manage thread switching to avoid “UI delays” or deadlocks. The original version of the extension uses single file generators as a custom tool. A custom tool is a COM component that implements the IVsSingleFileGenerator interface. Implementing single-file generators in 2026 feels really outdated.

Old Command Implementation - SingleFileCodeGenerator.cs:

[ComVisible(true)]
public abstract class SingleFileCodeGenerator : IVsSingleFileGenerator
{
    public int Generate(
        string wszInputFilePath,
        string bstrInputFileContents,
        string wszDefaultNamespace,
        IntPtr[] rgbOutputFileContents,
        out uint pcbOutput,
        IVsGeneratorProgress pGenerateProgress)
    {
        // Strict thread affinity check required
        if (!TestingUtility.IsRunningFromUnitTest)
            ThreadHelper.ThrowIfNotOnUIThread();

        // Blocking generation on the UI thread
        var codeGenerator = Factory.Create(...);
        var code = codeGenerator.GenerateCode();

        // Report progress
    }
}

In the new model, we simply implement ExecuteCommandAsync and use the IClientContext to interact with the IDE.

New Command Implementation (RefitterCommands.cs):

[VisualStudioContribution]
public class GenerateRefitterCommand(TraceSource traceSource, ExtensionSettingsProvider settingsProvider)
    : GenerateRefitterBaseCommand(traceSource, settingsProvider)
{
    public override async Task ExecuteCommandAsync(
        IClientContext context,
        CancellationToken cancellationToken)
    {
        // Fully async execution without UI thread blocking
        await GenerateCodeAsync(
            await context.GetInputFileAsync(cancellationToken),
            await context.GetDefaultNamespaceAsync(cancellationToken),
            cancellationToken);
    }
}

Background Progress Reporting

Since our code generation can take a few seconds (or more for large specs), providing feedback is essential. The new SDK makes it incredibly easy to show a progress indicator in the Visual Studio status bar or a background task window.

Here’s how easy it is to implement:

public async Task GenerateCodeAsync(...)
{
    using var progress = await Extensibility.Shell().StartProgressReportingAsync(
        "Generating code with Refitter",
        new ProgressReporterOptions(true), // true = indeterminate/cancellable
        cancellationToken);

    progress.Report(10, $"Starting Refitter code generation for: {inputFilename}");

    // Do the heavy lifting...
    var csharpCode = await GenerateCodeInternalAsync(..., progress, cancellationToken);

    progress.Report(90, "Writing generated code...");
    await File.WriteAllTextAsync(outputFile, csharpCode, cancellationToken);
}

A New Settings Experience

The old Visual Studio SDK used the DialogPage class to create options pages, which often looked like standard Windows Forms property grids. The new model introduces a modern, declarative way to define settings.

Here’s an example of how settings are defined in the new model. We simply define a static class with properties decorated with the [VisualStudioContribution] attribute:

internal static class GeneralSettings
{
    [VisualStudioContribution]
    internal static SettingCategory GeneralCategory { get; } = new("general", "%Settings.General.DisplayName%", SettingsRoot.RootCategory)
    {
        Description = "%Settings.General.Description%",
        GenerateObserverClass = true,
        Order = 0,
    };

    [VisualStudioContribution]
    internal static Setting.String JavaPath { get; } = new(
        "javaPath",
        "%Settings.JavaPath.DisplayName%",
        GeneralCategory,
        string.Empty)
    {
        Description = "%Settings.JavaPath.Description%",
    };

    // ... other settings
}

Reading these settings is also straightforward and fully asynchronous:

public class ExtensionSettingsProvider(VisualStudioExtensibility extensibility)
{
    public async Task<IGeneralOptions> GetGeneralOptionsAsync(CancellationToken cancellationToken)
    {
        var values = await extensibility.Settings().ReadEffectiveValuesAsync(
        [
            GeneralSettings.JavaPath,
            GeneralSettings.NpmPath,
            GeneralSettings.NSwagPath,
            // ...
        ],
        cancellationToken);

        return new GeneralOptions(values);
    }
}

I’ve migrated all the tool-specific settings to this new API. Here is what the new settings UI looks like:

We can now define settings for each generator, such as NSwag, AutoRest, and Refitter, with rich UI support.

Dialogs and User Input

Sometimes we need input from the user, like a URL for an OpenAPI specification. In the old days, I would have had to build a custom WPF Window or Windows Form. Now, I can use the built-in ShowPromptAsync method for a consistent, native look and feel.

This snippet from CommandExtensions.cs shows how we prompt for a URL:

public static async Task<string?> AddNewOpenApiFileAsync(
    this Command command,
    IClientContext context,
    CancellationToken cancellationToken)
{
    var inputUrl = await command.Extensibility.Shell().ShowPromptAsync(
        "Enter URL to OpenAPI Specifications",
        new InputPromptOptions
        {
            DefaultText = "Example: https://petstore3.swagger.io/api/v3/openapi.json",
            Icon = ImageMoniker.KnownValues.URLInputBox,
            Title = "REST API Client Code Generator",
        },
        cancellationToken);

    return inputUrl;
}

Creating Custom Dialogs with XAML

For more complex scenarios, like the About Dialog, the new model allows us to define UI using standard XAML data templates. This is a huge win for maintainability, as we can separate the UI definition from the logic.

Here’s a snippet of the XAML definition for the About Dialog:

<DataTemplate xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
              xmlns:vs="http://schemas.microsoft.com/visualstudio/extensibility/2022/xaml">
  <StackPanel Orientation="Vertical" MinWidth="500" Margin="20">
    <TextBlock FontSize="18" FontWeight="Bold" Margin="0,0,0,10"
               Text="{Binding DisplayName}" />

    <TextBlock FontSize="12" Margin="0,0,0,5"
               Text="{Binding Description}" TextWrapping="Wrap" />

    <StackPanel Orientation="Horizontal" Margin="0,10,0,5">
      <TextBlock FontWeight="SemiBold" Text="Version: " />
      <TextBlock Text="{Binding Version}" />
    </StackPanel>

    <!-- ... more UI elements ... -->
  </StackPanel>
</DataTemplate>

And the backing C# model uses the RemoteUserControl base class:

internal class AboutDialog(
    VisualStudioExtensibility extensibility,
    string displayName,
    string description,
    string version)
    : RemoteUserControl(new AboutDialogData(extensibility, displayName, description, version))
{
    [DataContract]
    internal class AboutDialogData : NotifyPropertyChangedObject
    {
        [DataMember]
        public string DisplayName { get; set; }

        [DataMember]
        public string Description { get; set; }

        [DataMember]
        public string Version { get; set; }

        // ...
    }
}

This clean separation of concerns makes building custom UI in Visual Studio extensions much more pleasant.

Code Reuse: The Core Library

Despite the massive architectural shift in the VSIX project, the “brains” of the operation—the code generation logic—remain largely unchanged.

Both the old (Dev17) and new (Extensibility) projects reference the same Core Library. This ensures that regardless of which version of the extension you use, the generated code quality and features remain identical. This made the migration much smoother, as I only had to focus on the “plumbing” of the extension rather than rewriting the generators themselves.

Conclusion

Migrating to the new Visual Studio Extensibility model has been a significant step forward. The performance gains from .NET 8.0, the stability of the out-of-process model, and the improved developer experience with modern APIs make it well worth the effort.

If you’re a Visual Studio extension author, I highly recommend looking into this new model. And if you’re a user of the REST API Client Code Generator, I hope you enjoy the faster, more stable experience!

This extension builds on years of OpenAPI tooling work. For related approaches to API client generation, see my posts on Kiota and Refitter, both of which offer alternative code generation strategies from OpenAPI specs.

Building a fast line of code counter app in Zig

2026-02-10T00:00:00+00:00

I recently wrote a CLI tool for counting lines of code in Zig. This was nothing more than a coding exercise and an experiment to see how fast a Zig compiled tool would be compared to the well-known tool cloc, which was originally written in Perl.

The source code is available on GitHub at https://github.com/christianhelle/clocz.

It only took me an evening to build, and GitHub Copilot wrote the GitHub workflows, README, install scripts, and the snapcraft.yaml file.

How it works

The implementation is quite straightforward. It uses std.fs.Dir.iterate to walk the directory tree. For each file found, a job is spawned in a std.Thread.Pool. This allows the tool to process multiple files in parallel, maximizing I/O and CPU usage.

fn walkDir(
    allocator: std.mem.Allocator,
    dir: std.fs.Dir,
    dir_path: []const u8,
    results: *results_mod.Results,
    pool: *std.Thread.Pool,
) !void {
    var iter = dir.iterate();
    while (try iter.next()) |entry| {
        // ... (skip hidden files and node_modules)

        const entry_path = try std.fs.path.join(allocator, &.{ dir_path, entry.name });
        switch (entry.kind) {
            .directory => {
                // ... (recursive call)
            },
            .file => {
                // Ownership of entry_path transfers to the job; the job frees it.
                pool.spawn(processFile, .{JobContext{
                    .allocator = allocator,
                    .path = entry_path,
                    .results = results,
                }}) catch {
                    allocator.free(entry_path);
                };
            },
            else => allocator.free(entry_path),
        }
    }
}

I added some basic filtering to skip hidden files (starting with .) and directories like node_modules and vendor, as these usually contain dependencies rather than source code. There’s also a file size limit of 128MB to avoid loading massive files into memory.

For language detection, I went with a simple extension-based lookup. The file extension is extracted, lower cased, and matched against a list of known languages. It supports over 60 languages, handling single-line and block comments specific to each language.

const entries = [_]Entry{
    // C family
    .{ .ext = "c",        .lang = cStyle("C") },
    .{ .ext = "h",        .lang = cStyle("C") },
    .{ .ext = "cpp",      .lang = cStyle("C++") },
    .{ .ext = "cc",       .lang = cStyle("C++") },
    .{ .ext = "cxx",      .lang = cStyle("C++") },
    .{ .ext = "hpp",      .lang = cStyle("C++") },
    .{ .ext = "hxx",      .lang = cStyle("C++") },
    .{ .ext = "cs",       .lang = cStyle("C#") },
    .{ .ext = "java",     .lang = cStyle("Java") },
    // and more...

pub fn detect(path: []const u8) ?Language {
    const ext = std.fs.path.extension(path);
    if (ext.len <= 1) return null;
    const ext_no_dot = ext[1..];

    // Lowercase into a small stack buffer (extensions are short)
    var buf: [32]u8 = undefined;
    if (ext_no_dot.len > buf.len) return null;
    const ext_lower = std.ascii.lowerString(buf[0..ext_no_dot.len], ext_no_dot);

    for (entries) |entry| {
        if (std.mem.eql(u8, entry.ext, ext_lower)) return entry.lang;
    }
    return null;
}

The actual line counting logic is a single-pass scan over the file content. It counts blank lines, single-line comments, block comments, and code lines. It uses a state machine-like approach to track if it’s inside a block comment, which handles nested comments and comments starting mid-line.

pub const Counts = struct {
    files: u64 = 0,
    blank: u64 = 0,
    comment: u64 = 0,
    code: u64 = 0,
};

pub fn countLines(buf: []const u8, lang: languages.Language) Counts {
    var counts = Counts{ .files = 1 };
    var in_block = false;

    // Strip a trailing newline so we don't count an extra blank line for it.
    const data = if (buf.len > 0 and buf[buf.len - 1] == '\n') buf[0 .. buf.len - 1] else buf;

    var lines = std.mem.splitScalar(u8, data, '\n');
    while (lines.next()) |raw_line| {
        // Trim \r for Windows line endings and leading/trailing whitespace.
        const line = std.mem.trim(u8, raw_line, " \t\r");

        if (line.len == 0) {
            counts.blank += 1;
            continue;
        }

        // Inside a block comment.
        if (in_block) {
            counts.comment += 1;
            if (lang.block_comment_end) |bce| {
                if (std.mem.indexOf(u8, line, bce) != null) {
                    in_block = false;
                }
            }
            continue;
        }

        // ... (check for start of block comment or single line comment)

        // It's a code line.
        counts.code += 1;

        // Check whether a block comment opens mid-line (e.g. `x = 1; /* start`).
        if (lang.block_comment_start) |bcs| {
            if (std.mem.indexOf(u8, line, bcs)) |bcs_pos| {
                // ... (check if block comment ends on same line)
            }
        }
    }

    return counts;
}

Command Line Parsing

Currently the tool only really a single functional argument, which is the folder to scan. I manually iterate through the arguments provided by std.process.argsAlloc. The implementation checks for flags like -h or --help and interprets any non-flag argument as the target directory path. If an unknown option is encountered, it helpfully prints the usage information and exits.

pub fn init(allocator: std.mem.Allocator) !Cli {
    const args = try std.process.argsAlloc(allocator);
    defer std.process.argsFree(allocator, args);

    // ...

    var path: []const u8 = ".";
    for (args[1..]) |arg| {
        if (std.mem.startsWith(u8, arg, "-h") or std.mem.startsWith(u8, arg, "--help")) {
            options.help = true;
        } else if (std.mem.startsWith(u8, arg, "-v") or std.mem.startsWith(u8, arg, "--version")) {
            options.version = true;
        } else if (arg.len > 0 and arg[0] != '-') {
            path = arg;
        } else {
            // ... (print error and exit)
        }
    }

    // ...
}

Performance and Progress

One of the goals was to see how fast Zig can be compared to the original Perl version. The tool reads files into memory buffers using readToEndAlloc (up to 128MB) and quickly scans for line breaks and comments. It also detects binary files to avoid counting them as source code.

/// Returns true if the buffer looks like a binary file (null byte in first 8KB).
pub fn isBinary(buf: []const u8) bool {
    const check = @min(buf.len, 8192);
    return std.mem.indexOfScalar(u8, buf[0..check], 0) != null;
}

While the main thread and worker threads are busy scanning, a separate thread runs a simple progress loop. It sleeps for 100ms and prints the current count of scanned files (\rScanning... {d} files), giving visual feedback without slowing down the processing.

pub fn loop(self: *ProgressPrinter) void {
    const stderr = std.fs.File.stderr();
    while (self.running.load(.acquire)) {
        std.Thread.sleep(100 * std.time.ns_per_ms);
        if (!self.running.load(.acquire)) break;
        const n = self.results.files_scanned.load(.monotonic);
        var buf: [64]u8 = undefined;
        const msg = std.fmt.bufPrint(&buf, "\rScanning... {d} files", .{n}) catch break;
        stderr.writeAll(msg) catch {};
    }
}

The final output is a sorted table showing the number of files, blank lines, comments, and code lines for each language, along with the total time taken and files processed per second.

Usage

The CLI is simple. You run clocz to scan the current directory, or clocz [path] to scan a specific directory. The -h and -v flags show help and version info respectively.

Here’s an example of the output for scanning a reasonably large system with a backend written in C# and a React frontend, running on a 10-year-old laptop with an Intel Core i7-7660U @ 4x 4GHz CPU with 8GB of RAM:

Scanned 10822 files

------------------------------------------------------------------------
Language                          files    blank    comment       code
------------------------------------------------------------------------
C#                                 4045    26273      19500     170743
TSX                                 720     5119       1248      58860
TypeScript                          726     4123       2585      43640
Markdown                             59     1347          0       4480
CSS                                   9      370         52       2889
PowerShell                           40      460        305       2046
HTML                                  4       32         12       1619
JavaScript                            4      193        167       1034
Shell                                 4       22         14        108
XML                                   1        0          0          9
------------------------------------------------------------------------
SUM:                               5612    37939      23883     285428
------------------------------------------------------------------------
Time=0.50s  (11203.0 files/s)

The tool is a single static binary with zero external dependencies, making it easy to distribute and run on Linux, macOS, and Windows.

Distribution

Since I’m lazy and wanted this to be easy to use, I asked GitHub Copilot to help me set up the distribution channels. It generated the install.sh and install.ps1 scripts for quick installation on Linux/macOS and Windows respectively using the latest Release version on Github.

It also wrote the snapcraft.yaml file so I could publish clocz to the Snap Store.

name: clocz
base: core22
version: '0.1.0'
summary: A fast line counter written in Zig
description: |
  A fast, multi-threaded command-line tool for counting lines of code.
grade: stable
confinement: strict

The GitHub Actions workflow (release.yml) builds binaries for Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64) and attaches them to the GitHub Release.

Conclusion

I was pleasantly surprised by how productive I could be with Zig after working with it on-and-off for half a year, building a performant and cross-platform tool in such a short amount of time. If you want to check it out or contribute, the source code is on GitHub at https://github.com/christianhelle/clocz.

This was part of my ongoing Zig learning journey. For more Zig projects, see HTTP File Runner, chlogr, argiope, and ZigFaker.

Integration Testing REST APIs with .http Files and HTTP File Runner

2026-01-26T00:00:00+00:00

Integration testing REST APIs is a crucial part of ensuring the reliability of micro-services and web applications. While there are many tools available, using simple .http files offers a lightweight and version-controllable approach that I really love.

In this post, I’ll explore how to use HTTP File Runner (or httprunner), a command-line tool I built in Rust, to execute advanced integration test scenarios using .http files. We’ll cover everything from variable management to conditional execution and CI/CD integration.

Getting Started

First, ensure you have httprunner installed. You can install it via a simple script or download a release from the GitHub repository.

# Linux/macOS
curl -fsSL https://christianhelle.com/httprunner/install | bash

# Windows
irm https://christianhelle.com/httprunner/install.ps1 | iex

If you’re on Ubuntu then you can also install it using snap

snap install httprunner

Once installed, you can run any .http file:

httprunner tests.http

Global Variables

You can define global variables at the top of your .http file using the @ syntax. This is perfect for values that are reused across multiple requests, like a base URL.

@HostAddress = https://httpbin.org
@ContentType = application/json

GET {{HostAddress}}/get
Content-Type: {{ContentType}}

Built-in Functions

httprunner provides built-in functions for dynamic value generation in your .http files. Functions are case-insensitive and automatically generate values when the request is executed.

Available Functions

`guid()` - Generate UUID

Generates a new UUID v4 (Universally Unique Identifier) in simple format (32 hex characters without dashes).

POST https://api.example.com/users
Content-Type: application/json

{
  "id": "guid()",
  "requestId": "GUID()"
}

`string()` - Generate Random String

Generates a random alphanumeric string of 20 characters.

POST https://api.example.com/test
Content-Type: application/json

{
  "sessionKey": "string()",
  "token": "STRING()"
}

`number()` - Generate Random Number

Generates a random number between 0 and 100 (inclusive).

POST https://api.example.com/data
Content-Type: application/json

{
  "randomValue": "number()",
  "percentage": "NUMBER()"
}

`base64_encode()` - Base64 Encoding

Encodes a string to Base64 format. The string must be enclosed in single quotes.

POST https://api.example.com/auth
Content-Type: application/json

{
  "credentials": "base64_encode('username:password')",
  "token": "BASE64_ENCODE('Hello, World!')"
}

`upper()` - Convert to Uppercase

Converts a string to uppercase. The string must be enclosed in single quotes.

POST https://api.example.com/data
Content-Type: application/json

{
  "code": "upper('hello, world')",
  "shout": "UPPER('quiet text')"
}

`lower()` - Convert to Lowercase

Converts a string to lowercase. The string must be enclosed in single quotes.

POST https://api.example.com/data
Content-Type: application/json

{
  "normalized": "lower('HELLO, WORLD')",
  "lowercase": "LOWER('Mixed Case Text')"
}

`name()` - Generate Full Name

Generates a random full name (first name + last name).

POST https://api.example.com/users
Content-Type: application/json

{
  "fullName": "name()",
  "displayName": "NAME()"
}

`first_name()` - Generate First Name

Generates a random first name.

POST https://api.example.com/users
Content-Type: application/json

{
  "firstName": "first_name()",
  "givenName": "FIRST_NAME()"
}

`last_name()` - Generate Last Name

Generates a random last name.

POST https://api.example.com/users
Content-Type: application/json

{
  "lastName": "last_name()",
  "surname": "LAST_NAME()"
}

`address()` - Generate Address

Generates a random full mailing address (street, city, postal code, country).

POST https://api.example.com/users
Content-Type: application/json

{
  "streetAddress": "address()",
  "mailingAddress": "ADDRESS()"
}

`email()` - Generate Email Address

Generates a random email address in the format firstname.lastname@domain.com.

POST https://api.example.com/users
Content-Type: application/json

{
  "email": "email()",
  "contactEmail": "EMAIL()"
}

`job_title()` - Generate Job Title

Generates a random job title.

POST https://api.example.com/users
Content-Type: application/json

{
  "title": "job_title()",
  "position": "JOB_TITLE()"
}

`lorem_ipsum(n)` - Generate Lorem Ipsum Text

Generates Lorem Ipsum placeholder text with the specified number of words. The parameter n determines how many words to generate.

POST https://api.example.com/content
Content-Type: application/json

{
  "summary": "lorem_ipsum(20)",
  "description": "LOREM_IPSUM(50)",
  "content": "Lorem_Ipsum(100)"
}

`getdate()` - Get Current Date

Returns the current local date in YYYY-MM-DD format.

POST https://api.example.com/events
Content-Type: application/json

{
  "eventDate": "getdate()",
  "createdDate": "GETDATE()"
}

`gettime()` - Get Current Time

Returns the current local time in HH:MM:SS format (24-hour).

POST https://api.example.com/logs
Content-Type: application/json

{
  "timestamp": "gettime()",
  "logTime": "GETTIME()"
}

`getdatetime()` - Get Current Date and Time

Returns the current local date and time in YYYY-MM-DD HH:MM:SS format.

POST https://api.example.com/records
Content-Type: application/json

{
  "createdAt": "getdatetime()",
  "timestamp": "GETDATETIME()"
}

`getutcdatetime()` - Get Current UTC Date and Time

Returns the current UTC date and time in YYYY-MM-DD HH:MM:SS format.

POST https://api.example.com/records
Content-Type: application/json

{
  "utcTimestamp": "getutcdatetime()",
  "serverTime": "GETUTCDATETIME()"
}

Environment Variables

For different environments (development, staging, production), you shouldn’t hard code values. httprunner supports loading variables from a http-client.env.json file, compatible with the VS Code REST Client extension. In most cases, the environment file would contain secrets like API keys or tokens that you don’t want to commit to version control.

Create a http-client.env.json file:

{
  "dev": {
    "HostAddress": "https://dev-api.example.com",
    "ApiKey": "dev-secret"
  },
  "prod": {
    "HostAddress": "https://api.example.com",
    "ApiKey": "prod-secret"
  }
}

Reference these variables in your .http file:

GET {{HostAddress}}/users
Authorization: Bearer {{ApiKey}}

Then run httprunner with the --env flag:

httprunner tests.http --env dev

Generating Environment Files

Manually managing http-client.env.json files can be tedious, especially when dealing with short-lived tokens or multiple environments. I recommend scripting the generation of this file.

Here is an example PowerShell script that fetches access tokens from Azure CLI and generates a comprehensive environment file for localhost, Docker, and development environments:

$management_api_tokens = az account get-access-token `
  --scope app://api.example.net/dev/management_api/.default | ConvertFrom-Json

$simulator_tokens = az account get-access-token `
  --scope app://api.example.net/dev/simulator/.default | ConvertFrom-Json

$environment = @{
  localhost = @{
    authorization = "Bearer " + $management_api_tokens.accessToken
    simulator_authorization = "Bearer " + $simulator_tokens.accessToken
    cpo = "http://localhost:8900"
    simulator = "http://localhost:8901"
    management_api = "http://localhost:8150"
  }
  docker = @{
    authorization = "Bearer " + $management_api_tokens.accessToken
    simulator_authorization = "Bearer " + $simulator_tokens.accessToken
    cpo = "http://host.docker.internal:8900"
    simulator = "http://host.docker.internal:8901"
    management_api = "http://host.docker.internal:8150"
  }
  dev = @{
    authorization = "Bearer " + $management_api_tokens.accessToken
    simulator_authorization = "Bearer " + $simulator_tokens.accessToken
    cpo = "https://ocpi.example.net"
    simulator = "https://ocpi-simulator.example.net"
    management_api = "https://management-api.example.net"
  }
}

Set-Content -Path ./http-client.env.json -Value ($environment | ConvertTo-Json -Depth 10)

Delays

Rate limiting is a common constraint when testing APIs. httprunner allows you to introduce delays either globally or per request. My personal use case would be eventually consistent systems where you want to wait for a certain state before proceeding.

To add a delay between every request in a run, use the CLI flag:

httprunner tests.http --delay 500

For more granular control, use comments in your .http file:

# @pre-delay 1000
# @post-delay 500
GET https://httpbin.org/get

@pre-delay: Wait before sending the request (in milliseconds).
@post-delay: Wait after the request completes (in milliseconds).

Timeouts

Network conditions can be unpredictable. You can configure timeouts to fail tests if an API is too slow. If you’re testing against a local development server, you might want to set a shorter timeout than the default 30 seconds.

# Wait up to 5 seconds for a response
# @timeout 5000 ms
GET https://api.example.net/delay/2

# Custom connection timeout (default is 30s)
# @connection-timeout 10 s
GET https://api.example.net/get

Supported units include ms, s, and m.

Request Chaining

One of the most powerful features for integration testing is chaining requests—using data from a previous response in a subsequent request. httprunner supports extracting values from headers, JSON bodies, and even the original request data.

Request Variable Syntax

The syntax for request variables is:

{{<request_name>.<source>.<part>.<path>}}

request_name: The name defined via # @name <name>
source: request or response
part: body or headers
path: The specific value to extract

Extraction Patterns

JSON Bodies: Use JSONPath syntax (e.g., $.user.id, $.items[0].name).
Headers: Use the header name (e.g., Content-Type, Location).
Full Body: Use * to extract the entire body.

Example Scenario

# @name create_user
POST https://api.example.com/users
Content-Type: application/json

{
  "username": "test_user",
  "role": "admin"
}

###

# @name login
POST https://api.example.com/login
Content-Type: application/json

{
  "username": "{{create_user.request.body.$.username}}",
  "password": "default_password"
}

###

# Use the token from login response
GET https://api.example.com/admin/dashboard
Authorization: Bearer {{login.response.body.$.token}}
X-User-Role: {{create_user.request.body.$.role}}

Conditional Execution

Complex test scenarios often require conditional logic. You might want to skip a cleanup step if the creation failed, or run specific tests only if a feature flag is enabled.

httprunner provides @dependsOn and @if directives.

# @name create_user
POST https://api.example.com/users
...

###

# Only run if create_user succeeded (HTTP 2xx)
# @dependsOn create_user
POST https://api.example.com/users/{{create_user.response.body.$.id}}/activate

###

# Only run if the user status is "active"
# @if create_user.response.body.$.status active
GET https://api.example.com/users/{{create_user.response.body.$.id}}

Assertions

No test is complete without verification. httprunner allows you to assert response status, headers, and body content directly in your .http file.

Basic Assertions

GET https://httpbin.org/json

EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"
EXPECTED_RESPONSE_BODY "slideshow"

Variable Substitution in Assertions

Crucially, variables are fully supported in assertions, allowing you to validate that a response matches input parameters or previous request data.

@expected_status=200
@user_id=123

# @name create_user
POST https://api.example.com/users
{ "id": "{{user_id}}" }

###

GET https://api.example.com/users/{{user_id}}

EXPECTED_RESPONSE_STATUS {{expected_status}}
EXPECTED_RESPONSE_BODY "{{user_id}}"
EXPECTED_RESPONSE_HEADERS "Location: /users/{{user_id}}"

This makes dynamic testing significantly easier, as you don’t need to hardcode expected values.

If any assertion fails, httprunner will report the test as failed and exit with a non-zero status code, which is essential for CI/CD pipelines.

Note: For requests that have assertions that expect failed responses (e.g., testing error handling), you can use EXPECTED_RESPONSE_STATUS to specify the expected failure status code (like 400 or 404). The “failed” request will no longer be flagged as failed, but instead will be validated against the expected status code and assertions.

Verbose Mode

When developing or debugging, you often need more insight into what httprunner is doing.

Use the --verbose flag to see detailed request and response information, including full headers and bodies. Add --pretty-json to format JSON payloads for readability.

httprunner tests.http --verbose --pretty-json

Discovery Mode

If you have tests scattered across multiple directories, use --discover to recursively find and execute all .http files.

httprunner --discover --verbose

Report Generation and Logging

For long-running tests or CI pipelines, console output isn’t enough. httprunner can generate structured reports and detailed logs.

Reports

Generate summary reports in Markdown (default) or HTML using the --report flag. HTML reports include responsive styling and dark mode support.

# Generate Markdown report
httprunner tests.http --report

# Generate HTML report
httprunner tests.http --report html

Logging

Use --log to save all console output to a file. This is useful for auditing and post-execution analysis.

httprunner tests.http --log execution.log

Export Mode

Sometimes you need the raw HTTP data for documentation or manual replay. The --export flag saves every request and response to individual, timestamped files.

httprunner tests.http --export

This will create files like GET_users_request_1738016400.log and GET_users_response_1738016400.log containing the exact payload sent and received.

Insecure HTTPS

When testing against local development environments or staging servers with self-signed certificates, SSL validation can be a blocker. Use --insecure to bypass these checks.

httprunner https://localhost:5001/api/tests.http --insecure

Note: Only use this in trusted environments!

Telemetry

httprunner collects anonymous usage data to help improve the tool. If you prefer to opt-out, you can disable it via a flag or environment variable.

# Disable via CLI
httprunner tests.http --no-telemetry

# Disable via Environment Variable
export HTTPRUNNER_TELEMETRY_OPTOUT=1
# or
export DO_NOT_TRACK=1

CI/CD Integration

Automating these tests in a CI/CD pipeline is straightforward. Since httprunner is available as a Docker image and a standalone binary, it fits easily into GitHub Actions or GitLab CI.

Here is an example GitHub Actions workflow:

name: Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install HTTP Runner
        run: snap install httprunner

      - name: Run API Tests
        run: tests/api.http --env staging --report markdown

Or, if you prefer installing the binary:

- name: Install HTTP Runner
  run: curl -fsSL https://christianhelle.com/httprunner/install | bash

- name: Run Tests
  run: httprunner tests/*.http --env staging --report html

This setup ensures that every change is validated against your API, providing fast feedback on regressions.

Conclusion

By combining the simplicity of .http files with the advanced features of httprunner, you can build a robust integration testing suite that lives right alongside your code. It’s version-controlled, easy to read, and powerful enough for complex scenarios involving authentication, chaining, and conditional logic.

Give it a try and let me know what you think!

This integration testing workflow builds on my earlier work with .http files. You can generate .http files from OpenAPI specs, convert them to automated tests with HttpTestGen, or test generated Refit clients with Alba.

Querying Azure Data Explorer from .NET with Cabazure.Kusto

2025-12-18T00:00:00+00:00

Querying Azure Data Explorer (Kusto) from .NET requires managing connections, embedding .kusto scripts, parametrizing queries, deserializing results, and handling pagination. It’s a lot of boilerplate—connection strings, credential chains, data readers, continuation tokens. Each project ends up with slightly different patterns. I found myself writing the same infrastructure code repeatedly.

That’s why I use Cabazure.Kusto—a .NET library written by my colleague @rickykaare that simplifies executing Kusto queries from .NET applications. Define your queries as records, embed .kusto scripts alongside your code, and let the framework handle connection management, parameter binding, result deserialization, and pagination. Your API endpoints become three lines of code.

Why Query Abstraction Matters

When you query Kusto directly, you manage low-level details: construct connection strings, authenticate with DefaultAzureCredential, open readers, map columns to objects, handle pagination tokens. This repeats across every endpoint. Each query becomes a Task that returns a list or a single object. Pagination requires passing session IDs and continuation tokens, then mapping response headers. It adds noise to your business logic.

Cabazure.Kusto removes this by providing a unified query interface. Define a query record, create a matching .kusto file, and inject IKustoProcessor. Call ExecuteAsync with your query and cancellation token. The framework handles authentication, script loading, parameter binding, result mapping, and pagination. Your controller focuses on business logic, not infrastructure.

Setting Up Cabazure.Kusto

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCabazureKusto(o =>
{
    o.HostAddress = new Uri("https://help.kusto.windows.net/");
    o.DatabaseName = "ContosoSales";
    o.Credential = new DefaultAzureCredential();
});

var app = builder.Build();

The options configure your Kusto cluster URL, target database, and authentication credential. DefaultAzureCredential supports managed identity, user sign-in, or environment variables—whatever your deployment requires.

Defining Query Records and `.kusto` Files

Queries are defined as C# records that inherit from KustoQuery<T>, where T is your result type. Each query lives alongside a .kusto file with the same name.

Create a query record:

namespace SampleApi.Queries;

using Cabazure.Kusto;
using SampleApi.Contracts;

public record CustomersQuery(
    int? CustomerId = null)
    : KustoQuery<Customer>;

The record properties become query parameters. Create a matching .kusto file in the same namespace directory:

declare query_parameters (
    customerId:long = long(null)
);
Customers
| where isnull(customerId) or customerId == CustomerKey
| project
    CustomerKey,
    FirstName,
    LastName,
    CompanyName,
    CityName,
    StateProvinceName,
    RegionCountryName,
    ContinentName,
    Gender,
    MaritalStatus,
    Education,
    Occupation

The .kusto file declares parameters that match your record properties (note the camelCase convention in the script). The Kusto Query Language (KQL) builds your actual query. The result columns map directly to your result type record.

Define your result type as a record:

namespace SampleApi.Contracts;

public record Customer(
    int CustomerKey,
    string FirstName,
    string LastName,
    string? CompanyName,
    string CityName,
    string StateProvinceName,
    string RegionCountryName,
    string ContinentName,
    string Gender,
    string MaritalStatus,
    string Education,
    string Occupation);

The property names and types must match the Kusto query’s output columns.

Executing Simple Queries

Once your query and result types are defined, executing is straightforward. Inject IKustoProcessor and call ExecuteAsync:

app.MapGet(
    "/customers/{customerId}",
    async static (
        int customerId,
        IKustoProcessor processor,
        CancellationToken cancellationToken)
        => await processor.ExecuteAsync(
            new CustomersQuery(customerId),
            cancellationToken) switch
        {
            [{ } customer] => Results.Ok(customer),
            _ => Results.NotFound(),
        })
    .WithName("GetCustomer");

The ExecuteAsync method returns an array of your result type. Use pattern matching or LINQ to extract the single result or handle the collection as needed. Behind the scenes, the framework loads the .kusto file, binds your record properties as parameters, connects to Kusto, executes the query, and deserializes rows into Customer objects.

Queries That Return Collections

For endpoints that return multiple results, use the same pattern:

app.MapGet(
    "/customers",
    async static (
        IKustoProcessor processor,
        CancellationToken cancellationToken)
        => await processor.ExecuteAsync(
            new CustomersQuery(),
            cancellationToken))
    .WithName("ListCustomers");

When ExecuteAsync returns without specifying pagination, it returns the full result array. Kusto imposes limits on result sizes, so for large datasets, implement pagination.

Pagination and Continuation Tokens

For endpoints serving paginated results, use the three-parameter overload of ExecuteAsync. This supports session-based continuation:

app.MapGet(
    "/customers",
    async static (
        [FromHeader(Name = "x-client-session-id")] string? sessionId,
        [FromHeader(Name = "x-max-item-count")] int? maxItemCount,
        [FromHeader(Name = "x-continuation-token")] string? continuationToken,
        IKustoProcessor processor,
        CancellationToken cancellationToken)
        => await processor.ExecuteAsync(
            new CustomersQuery(),
            sessionId,
            maxItemCount ?? 100,
            continuationToken,
            cancellationToken))
    .WithName("ListCustomers");

The processor returns a PagedResult<T>:

public record PagedResult<T>(
    IReadOnlyList<T> Items,
    string? ContinuationToken);

Your response includes Items (the current page) and a ContinuationToken (for fetching the next page). The client passes the token in subsequent requests to continue pagination. The sessionId maintains state across multiple requests, and maxItemCount controls page size.

Complex Queries and Aggregations

Kusto excels at analytical queries. Create a query for customer sales aggregation:

namespace SampleApi.Queries;

using Cabazure.Kusto;
using SampleApi.Contracts;

public record CustomerSalesQuery
    : KustoQuery<CustomerSales>
{
}

With the matching .kusto file:

Customers
| join kind=inner SalesFact on CustomerKey
| extend CustomerName = strcat(FirstName, ' ', LastName)
| summarize 
    SalesAmount = todecimal(round(sum(SalesAmount), 2)),
    TotalCost = todecimal(round(sum(TotalCost), 2))
  by CustomerKey, CustomerName
| take 100

And the result type:

namespace SampleApi.Contracts;

public record CustomerSales(
    int CustomerKey,
    string CustomerName,
    decimal SalesAmount,
    decimal TotalCost);

Execute it the same way:

app.MapGet("/customer-sales", 
    (IKustoProcessor processor, CancellationToken cancellationToken)
        => processor.ExecuteAsync(
            new CustomerSalesQuery(), 
            cancellationToken))
    .WithName("GetCustomerSales");

Kusto’s analytical operators (join, summarize, extend, take, top, etc.) let you build aggregations and pivots without multiple round-trips. The query runs server-side; only results are deserialized.

The Sample Application

The Cabazure.Kusto repository includes a samples/SampleApi project that demonstrates these patterns using the public Azure Data Explorer cluster with the ContosoSales database. It shows real endpoints: listing customers, fetching a single customer, and querying customer sales data.

To run the sample:

Clone the repository
Navigate to samples/SampleApi
Run dotnet run
Visit http://localhost:5000/swagger to explore endpoints

The sample uses DefaultAzureCredential, which automatically discovers credentials in your environment. For local testing, ensure you have the Azure CLI authenticated.

When to Use Cabazure.Kusto

Cabazure.Kusto shines when:

You query Kusto frequently from a .NET application. Boilerplate reduction pays off immediately.
You have many query types and want consistency. All queries follow the same record + .kusto file pattern.
You need pagination. The built-in continuation token handling is cleaner than managing it manually.
You want strong typing. Your queries are C# records with compile-time type safety; result deserialization is automatic and type-checked.
You’re building an API with multiple Kusto endpoints. Minimal setup per endpoint means faster development.

It’s less useful if you have a single, massive query or if you’re building an interactive query tool. For those scenarios, use the Kusto SDK directly.

Under the Hood

The library provides a simple but powerful abstraction:

public interface IKustoProcessor
{
    Task ExecuteAsync(
        IKustoCommand command,
        CancellationToken cancellationToken);

    Task<T?> ExecuteAsync<T>(
        IKustoQuery<T> query,
        CancellationToken cancellationToken);

    Task<PagedResult<T>?> ExecuteAsync<T>(
        IKustoQuery<IReadOnlyList<T>> query,
        string? sessionId,
        int? maxItemCount,
        string? continuationToken,
        CancellationToken cancellationToken);
}

When you call ExecuteAsync, the processor:

Locates the .kusto file matching your query record’s namespace and name
Binds your record properties to Kusto query parameters
Authenticates using the configured credential
Executes the query against your Kusto cluster
Deserializes results into your result type
Returns the populated objects (or a paged result with a continuation token)

All of this happens transparently. Your code is clean and focused.

Getting Started

To use Cabazure.Kusto in your project:

Install the NuGet package: dotnet add package Cabazure.Kusto
Register in Program.cs with your cluster URL, database, and credential
Create a query record for each query type
Add a matching .kusto file alongside your query record
Define a result type record matching your Kusto columns
Inject IKustoProcessor and call ExecuteAsync

The README in the Cabazure.Kusto repository provides full documentation and additional examples.

Conclusion

Building analytics APIs shouldn’t require managing low-level Kusto infrastructure. Cabazure.Kusto removes the boilerplate so you can focus on query logic and API contracts. If you query Azure Data Explorer from .NET, give it a try. The source code is on GitHub at https://github.com/Cabazure/Cabazure.Kusto.

Building a Github Changelog Generator in Zig

2025-11-25T00:00:00+00:00

I recently built a GitHub changelog generator in Zig. The tool fetches GitHub releases and merged pull requests from any public repository, then automatically generates a Markdown changelog organized by version and category (Features, Bug Fixes, Other).

The source code is available on GitHub at https://github.com/christianhelle/chlogr.

Like my most of my recent projects, GitHub Copilot wrote most of the boilerplate including GitHub workflows, README, install scripts, and snapcraft.yaml. The core functionality took a few evenings to build and test.

How it works

The changelog generator orchestrates several key components. It parses command-line arguments, resolves a GitHub token (with intelligent fallback), fetches GitHub releases and merged pull requests from the API, groups pull requests by release and category, and formats the result as Markdown.

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    const args = try std.process.argsAlloc(allocator);
    defer std.process.argsFree(allocator, args);

    // Parse CLI arguments
    const cli_parser = cli.CliParser.init(allocator);
    const parsed_args = cli_parser.parse(args) catch |err| {
        if (err == error.HelpRequested) {
            cli.CliParser.printHelp();
            return;
        }
        std.debug.print("Error: {}\n", .{err});
        cli.CliParser.printHelp();
        return err;
    };

    // Validate required arguments
    if (parsed_args.repo == null) {
        std.debug.print("Error: --repo is required\n\n", .{});
        cli.CliParser.printHelp();
        return error.MissingRequiredArgs;
    }

    // Resolve GitHub token (optional - can work without token for public repos)
    const resolver = token_resolver.TokenResolver.init(allocator);
    const resolved_token = try resolver.resolve(parsed_args.token);
    defer resolver.deinit(resolved_token);

    // ... fetch and generate changelog
}

The main flow is straightforward: validate inputs, resolve credentials, fetch data, generate the changelog structure, format it as Markdown, and write to a file.

Command Line Interface

The CLI parser handles flag parsing and validation. It supports required arguments like --repo and optional ones like --token, --output, and --exclude-labels.

pub const CliArgs = struct {
    repo: ?[]const u8 = null,
    token: ?[]const u8 = null,
    output: []const u8 = "CHANGELOG.md",
    since_tag: ?[]const u8 = null,
    until_tag: ?[]const u8 = null,
    exclude_labels: ?[]const u8 = null,
};

pub fn parse(_: CliParser, args: []const []const u8) !CliArgs {
    var result = CliArgs{};
    var i: usize = 1; // Skip program name

    while (i < args.len) : (i += 1) {
        const arg = args[i];

        if (std.mem.eql(u8, arg, "--repo")) {
            i += 1;
            if (i >= args.len) return error.MissingRepoValue;
            result.repo = args[i];
        } else if (std.mem.eql(u8, arg, "--token")) {
            i += 1;
            if (i >= args.len) return error.MissingTokenValue;
            result.token = args[i];
        } else if (std.mem.eql(u8, arg, "--output")) {
            i += 1;
            if (i >= args.len) return error.MissingOutputValue;
            result.output = args[i];
        } else if (std.mem.eql(u8, arg, "--exclude-labels")) {
            i += 1;
            if (i >= args.len) return error.MissingExcludeLabelsValue;
            result.exclude_labels = args[i];
        } else if (std.mem.eql(u8, arg, "--help") or std.mem.eql(u8, arg, "-h")) {
            return error.HelpRequested;
        }
    }

    return result;
}

The parser increments through arguments, recognizing flags and their values. Unknown arguments trigger an error with helpful usage information.

Token Resolution with Fallback Chain

One of the key features is smart GitHub token resolution. The tool attempts to find a token in this order: the --token flag, the GITHUB_TOKEN environment variable, the GH_TOKEN environment variable, or by running the gh auth token command.

pub const ResolvedToken = struct {
    value: []const u8,
    has_token: bool,
    is_owned: bool,
};

pub fn resolve(self: TokenResolver, provided_token: ?[]const u8) !ResolvedToken {
    // 1. Check provided token (not owned - don't free)
    if (provided_token) |token| {
        if (token.len > 0) {
            return ResolvedToken{
                .value = token,
                .has_token = true,
                .is_owned = false,
            };
        }
    }

    // 2. Check GITHUB_TOKEN env var (owned - must free)
    if (std.process.getEnvVarOwned(self.allocator, "GITHUB_TOKEN")) |token| {
        if (token.len > 0) {
            std.debug.print("Using GITHUB_TOKEN from environment variable\n", .{});
            return ResolvedToken{
                .value = token,
                .has_token = true,
                .is_owned = true,
            };
        } else {
            self.allocator.free(token);
        }
    } else |err| {
        if (err != error.EnvironmentVariableNotFound) return err;
    }

    // 3. Check GH_TOKEN env var (owned - must free)
    if (std.process.getEnvVarOwned(self.allocator, "GH_TOKEN")) |token| {
        if (token.len > 0) {
            std.debug.print("Using GH_TOKEN from environment variable\n", .{});
            return ResolvedToken{
                .value = token,
                .has_token = true,
                .is_owned = true,
            };
        } else {
            self.allocator.free(token);
        }
    } else |err| {
        if (err != error.EnvironmentVariableNotFound) return err;
    }

    // 4. Try to get token from gh CLI (owned - must free)
    if (self.getTokenFromGhCli()) |token| {
        std.debug.print("Using token from 'gh auth token' command\n", .{});
        return ResolvedToken{
            .value = token,
            .has_token = true,
            .is_owned = true,
        };
    } else |err| {
        if (err != error.GhCliExited and err != error.EmptyToken and err != error.FileNotFound) return err;
    }

    // No token found - return empty token but don't error
    std.debug.print("No GitHub token provided or found - proceeding without token\n", .{});
    return ResolvedToken{
        .value = "",
        .has_token = false,
        .is_owned = false,
    };
}

The resolver is smart about memory management—it tracks whether the returned token is borrowed (from the caller or command-line) or owned (from environment or subprocess), and only frees what it allocated. This is important in Zig where manual memory management is the default.

GitHub API Integration

The API client wraps HTTP requests with proper headers and JSON parsing. It fetches GitHub releases (via the Releases API) and merged pull requests from the GitHub API.

pub const GitHubApiClient = struct {
    allocator: std.mem.Allocator,
    http_client: http_client.HttpClient,
    repo: []const u8,

    pub fn init(allocator: std.mem.Allocator, token: []const u8, repo: []const u8) GitHubApiClient {
        return GitHubApiClient{
            .allocator = allocator,
            .http_client = http_client.HttpClient.init(allocator, token),
            .repo = repo,
        };
    }

    pub fn getReleases(self: *GitHubApiClient) ![]models.Release {
        const endpoint = try std.fmt.allocPrint(self.allocator, "/repos/{s}/releases", .{self.repo});
        defer self.allocator.free(endpoint);

        const response = try self.http_client.get(endpoint);
        defer self.allocator.free(response.body);

        if (response.status != .ok) {
            return error.GitHubApiError;
        }

        // Parse JSON response with ignoring unknown fields
        var parsed = try std.json.parseFromSlice(
            []models.Release,
            self.allocator,
            response.body,
            .{ .ignore_unknown_fields = true },
        );
        defer parsed.deinit();

        // Deep copy releases with string duplication
        var releases = try std.ArrayList(models.Release).initCapacity(self.allocator, parsed.value.len);
        for (parsed.value) |release| {
            releases.appendAssumeCapacity(.{
                .tag_name = try self.allocator.dupe(u8, release.tag_name),
                .name = try self.allocator.dupe(u8, release.name),
                .published_at = try self.allocator.dupe(u8, release.published_at),
            });
        }
        return try releases.toOwnedSlice(self.allocator);
    }

    pub fn getMergedPullRequests(self: *GitHubApiClient, per_page: u32) ![]models.PullRequest {
        const endpoint = try std.fmt.allocPrint(
            self.allocator,
            "/repos/{s}/pulls?state=closed&per_page={d}&sort=updated&direction=desc",
            .{ self.repo, per_page },
        );
        defer self.allocator.free(endpoint);

        const response = try self.http_client.get(endpoint);
        defer self.allocator.free(response.body);

        if (response.status != .ok) {
            return error.GitHubApiError;
        }

        var parsed = try std.json.parseFromSlice(
            []models.PullRequest,
            self.allocator,
            response.body,
            .{ .ignore_unknown_fields = true },
        );
        defer parsed.deinit();

        // Deep copy PRs with string and struct duplication
        var prs = try std.ArrayList(models.PullRequest).initCapacity(self.allocator, parsed.value.len);
        for (parsed.value) |pr| {
            // Copy labels...
            var labels = try std.ArrayList(models.Label).initCapacity(self.allocator, pr.labels.len);
            for (pr.labels) |label| {
                labels.appendAssumeCapacity(.{
                    .name = try self.allocator.dupe(u8, label.name),
                    .color = try self.allocator.dupe(u8, label.color),
                });
            }

            prs.appendAssumeCapacity(.{
                .number = pr.number,
                .title = try self.allocator.dupe(u8, pr.title),
                .body = if (pr.body) |body| try self.allocator.dupe(u8, body) else null,
                .html_url = try self.allocator.dupe(u8, pr.html_url),
                .user = .{
                    .login = try self.allocator.dupe(u8, pr.user.login),
                    .html_url = try self.allocator.dupe(u8, pr.user.html_url),
                },
                .labels = try labels.toOwnedSlice(self.allocator),
                .merged_at = if (pr.merged_at) |merged| try self.allocator.dupe(u8, merged) else null,
            });
        }
        return try prs.toOwnedSlice(self.allocator);
    }
};

The API client handles the quirk of Zig’s ownership model: it deep-copies JSON-parsed data into owned allocations since the parser’s temporary slice is freed after deinit(). It also specifies .ignore_unknown_fields to future-proof against API changes.

Changelog Generation and Grouping

The changelog generator groups pull requests by release and category. It uses a HashMap to collect entries by category for each release, then converts them to arrays.

pub const ChangelogGenerator = struct {
    allocator: std.mem.Allocator,
    exclude_labels: ?[]const u8 = null,

    fn categorizeEntry(_: ChangelogGenerator, labels: []models.Label) []const u8 {
        for (labels) |label| {
            if (std.mem.eql(u8, label.name, "feature") or std.mem.eql(u8, label.name, "enhancement")) {
                return "Features";
            } else if (std.mem.eql(u8, label.name, "bug") or std.mem.eql(u8, label.name, "bugfix")) {
                return "Bug Fixes";
            }
        }
        return "Merged Pull Requests";
    }

    pub fn generate(
        self: ChangelogGenerator,
        releases: []models.Release,
        prs: []models.PullRequest,
    ) !Changelog {
        var result = try std.ArrayList(ChangelogRelease).initCapacity(self.allocator, releases.len);

        for (releases) |release| {
            var sections_map = std.StringHashMap(std.ArrayList(ChangelogEntry)).init(self.allocator);
            defer {
                var it = sections_map.iterator();
                while (it.next()) |entry| {
                    entry.value_ptr.deinit(self.allocator);
                }
                sections_map.deinit();
            }

            for (prs) |pr| {
                if (self.shouldExclude(pr.labels)) continue;
                if (pr.merged_at) |merged_at| {
                    if (!isBefore(merged_at, release.published_at)) continue;
                } else {
                    continue;
                }

                const category = self.categorizeEntry(pr.labels);

                var section_list = sections_map.getOrPut(category) catch continue;
                if (!section_list.found_existing) {
                    const arr = try std.ArrayList(ChangelogEntry).initCapacity(self.allocator, prs.len);
                    section_list.value_ptr.* = arr;
                }

                const entry = ChangelogEntry{
                    .title = pr.title,
                    .url = pr.html_url,
                    .author = pr.user.login,
                    .number = pr.number,
                };

                try section_list.value_ptr.append(self.allocator, entry);
            }

            var sections_array = try std.ArrayList(ChangelogSection).initCapacity(self.allocator, sections_map.count());

            var it = sections_map.iterator();
            while (it.next()) |entry| {
                const changelog_section = ChangelogSection{
                    .name = entry.key_ptr.*,
                    .entries = try entry.value_ptr.toOwnedSlice(self.allocator),
                };
                sections_array.appendAssumeCapacity(changelog_section);
            }

            const release_entry = ChangelogRelease{
                .version = release.tag_name,
                .date = release.published_at,
                .sections = try sections_array.toOwnedSlice(self.allocator),
            };

            result.appendAssumeCapacity(release_entry);
        }

        return Changelog{ .releases = try result.toOwnedSlice(self.allocator), .unreleased = unreleased };
    }
};

The generator also creates an “Unreleased Changes” section for pull requests merged after the latest release. Date comparison is done as string slicing (extracting the date portion before the T), which works for ISO 8601 formatted timestamps.

Markdown Formatting

The formatter converts the changelog structure into Markdown strings, then writes to a file. It uses a string concatenation pattern, allocating small parts and combining them.

pub fn formatWithUnreleased(
    self: MarkdownFormatter,
    releases: []changelog_generator.ChangelogRelease,
    unreleased: ?changelog_generator.UnreleasedChanges,
) ![]u8 {
    var parts = try std.ArrayList([]u8).initCapacity(self.allocator, total_items + 20);
    defer parts.deinit(self.allocator);

    try parts.append(self.allocator, try self.allocator.dupe(u8, "# Changelog\n\n"));

    if (unreleased) |un| {
        try parts.append(self.allocator, try self.allocator.dupe(u8, "## [Unreleased Changes]\n\n"));

        for (un.sections) |section| {
            const section_header = try std.fmt.allocPrint(self.allocator, "### {s}\n", .{section.name});
            try parts.append(self.allocator, section_header);

            for (section.entries) |entry| {
                const entry_line = try std.fmt.allocPrint(self.allocator, "- {s} ([#{d}]({s})) (@{s})\n", .{
                    entry.title,
                    entry.number,
                    entry.url,
                    entry.author,
                });
                try parts.append(self.allocator, entry_line);
            }

            try parts.append(self.allocator, try self.allocator.dupe(u8, "\n"));
        }
    }

    for (releases) |release| {
        const header = try std.fmt.allocPrint(
            self.allocator,
            "## [{s}](https://github.com/owner/repo/releases/tag/{s}) - {s}\n\n",
            .{ release.version, release.version, release.date },
        );
        try parts.append(self.allocator, header);

        // ... format sections and entries
    }

    // Calculate total length
    var total_len: usize = 0;
    for (parts.items) |part| {
        total_len += part.len;
    }

    // Allocate result and concatenate
    var result = try self.allocator.alloc(u8, total_len);
    var offset: usize = 0;
    for (parts.items) |part| {
        @memcpy(result[offset .. offset + part.len], part);
        offset += part.len;
        self.allocator.free(part);
    }

    return result;
}

This approach avoids repeated allocations and reallocations by pre-calculating the total size before allocating once and copying chunks into the final buffer.

Usage

Using the tool is simple. For a public repository with anonymous access:

$ chlogr --repo github/cli --output CHANGELOG.md

GitHub Changelog Generator v0.1.0
Repo: github/cli
Output: CHANGELOG.md
Token: none (anonymous access - may have lower rate limits)
  To get higher rate limits, provide a token via --token flag, GITHUB_TOKEN env var, GH_TOKEN env var, or gh CLI

Fetching data from GitHub...
Found 142 releases and 523 pull requests
Changelog written to CHANGELOG.md

With a token for higher rate limits:

$ chlogr --repo github/cli --token ghp_xxxxxxxx --output HISTORY.md

GitHub Changelog Generator v0.1.0
Repo: github/cli
Output: HISTORY.md
Using token from environment variable
Token: ******* (truncated)

Fetching data from GitHub...
Found 142 releases and 523 pull requests
Changelog written to HISTORY.md

To exclude certain labels from the changelog:

chlogr --repo github/cli --exclude-labels "duplicate,wontfix" --output CHANGELOG.md

Note: The flags --since-tag and --until-tag are currently parsed but not yet wired into the changelog generator. They are reserved for future date-range filtering functionality.

The generated Markdown looks like:

# Changelog

## [Unreleased Changes]

### Features

- Add new experimental feature (#456) (@alice)

### Bug Fixes

- Fix critical crash in parser (#457) (@bob)

## [v1.2.0](https://github.com/github/cli/releases/tag/v1.2.0) - 2024-01-15

### Features

- Add authentication command (#440) (@charlie)
- Support for new API endpoints (#441) (@alice)

### Bug Fixes

- Fix URL encoding issue (#442) (@bob)

### Merged Pull Requests

- Update documentation (#443) (@charlie)

## [v1.1.0](https://github.com/github/cli/releases/tag/v1.1.0) - 2024-01-10

...

Building and Testing

Building the tool is straightforward with Zig’s build system:

zig build

This compiles the binary to zig-out/bin/chlogr. The build file also includes an integration test target:

zig build test

The integration tests use mock GitHub API responses to verify changelog grouping, categorization, and Markdown formatting without making real API calls.

The build.zig configuration is minimal:

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "chlogr",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });

    b.installArtifact(exe);

    const run_cmd = b.addRunArtifact(exe);
    if (b.args) |args| {
        run_cmd.addArgs(args);
    }

    const run_step = b.step("run", "Run the app");
    run_step.dependOn(&run_cmd.step);

    // Integration test...
}

Distribution

Like my previous Zig projects, the installation is kept simple. The install.sh script downloads the latest release binary for Linux or macOS from GitHub Releases:

#!/usr/bin/env bash
set -euo pipefail

REPO="christianhelle/chlogr"
INSTALL_DIR="${INSTALL_DIR:-$HOME/.local/bin}"
tmp_dir=""

cleanup() {
  if [ -n "${tmp_dir:-}" ] && [ -d "$tmp_dir" ]; then
    rm -rf -- "$tmp_dir"
  fi
}

detect_platform() {
  local os arch
  os="$(uname -s)"
  arch="$(uname -m)"

  case "$os" in
  Linux) os="linux" ;;
  Darwin) os="macos" ;;
  *)
    echo "Unsupported OS: $os" >&2
    exit 1
    ;;
  esac

  case "$arch" in
  x86_64 | amd64) arch="x86_64" ;;
  aarch64 | arm64) arch="aarch64" ;;
  *)
    echo "Unsupported architecture: $arch" >&2
    exit 1
    ;;
  esac

  echo "${os}-${arch}"
}

main() {
  local platform artifact_name url

  platform="$(detect_platform)"
  artifact_name="chlogr-${platform}.tar.gz"

  echo "Detecting platform: ${platform}"

  url="$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" |
    grep -o "\"browser_download_url\": *\"[^\"]*${artifact_name}\"" |
    head -1 |
    cut -d'"' -f4)"

  if [ -z "$url" ]; then
    echo "Error: could not find release asset ${artifact_name}" >&2
    exit 1
  fi

  tmp_dir="$(mktemp -d)"
  trap cleanup EXIT

  echo "Downloading ${url}..."
  curl -fsSL "$url" -o "${tmp_dir}/${artifact_name}"

  echo "Installing to ${INSTALL_DIR}..."
  tar xzf "${tmp_dir}/${artifact_name}" -C "$tmp_dir"
  install -d "$INSTALL_DIR"
  install -m 755 "${tmp_dir}/chlogr" "$INSTALL_DIR/chlogr"

  echo "chlogr installed to ${INSTALL_DIR}/chlogr"
}

main

For Windows, install.ps1 downloads and unzips the Windows x86_64 binary:

$ErrorActionPreference = 'Stop'

$repo = "christianhelle/chlogr"
$artifact = "chlogr-windows-x86_64.zip"
$installDir = "$env:USERPROFILE\.local\bin"

Write-Host "Fetching latest release..."
$release = Invoke-RestMethod -Uri "https://api.github.com/repos/$repo/releases/latest"
$asset = $release.assets | Where-Object { $_.name -eq $artifact }

if (-not $asset) {
    Write-Error "Could not find release asset: $artifact"
    exit 1
}

$url = $asset.browser_download_url
$tmpFile = Join-Path $env:TEMP $artifact

Write-Host "Downloading $url..."
Invoke-WebRequest -Uri $url -OutFile $tmpFile

Write-Host "Installing to $installDir..."
New-Item -ItemType Directory -Force -Path $installDir | Out-Null
Expand-Archive -Path $tmpFile -DestinationPath $installDir -Force
Remove-Item $tmpFile -Force

# Add to user PATH if not already present
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath -notlike "*$installDir*") {
    [Environment]::SetEnvironmentVariable("Path", "$userPath;$installDir", "User")
    Write-Host "Added $installDir to user PATH (restart your terminal to use)"
}

Write-Host "chlogr installed to $installDir\chlogr.exe"

GitHub Actions builds tar.gz archives for Linux (x86_64 and aarch64) and macOS (x86_64 and aarch64), and a zip archive for Windows (x86_64). These are automatically attached to releases via the workflow.

Known Limitations and Future Work

The current implementation has several limitations worth noting:

GitHub Releases Required: The tool uses the GitHub Releases API, not raw Git tags. A repository with only tags but no releases will not generate a changelog. Releases must be explicitly created.
Fixed PR Pagination: The tool fetches a fixed number of pull requests (100 per page). Large repositories with thousands of pull requests may have incomplete results unless pagination is enhanced.
Placeholder Release Links: Generated Markdown release headers use hard-coded placeholder links (https://github.com/owner/repo/releases/tag/{tag}). The actual repository owner and name are not yet wired into the formatter.
Date Range Filtering Not Implemented: The --since-tag and --until-tag flags are parsed but not yet connected to the changelog generator logic. They are reserved for future implementation.
Label Filtering by Substring: The --exclude-labels option uses simple substring matching rather than proper CSV parsing. For example, “wontfix” would also match a label named “wontfixme”.
Per-Release Grouping Overlap: Pull requests are grouped by checking whether they merged before a given release date. There is no lower bound per release, so older pull requests can theoretically appear in multiple release sections if they are manually re-categorized.
No Caching: Each run makes fresh API calls. For frequent changelog generation, caching would improve performance.
Basic HTTP Client: The HTTP client is functional but minimal. Testing uses mock data rather than real API calls.

Conclusion

Building chlogr was a good exercise in working with Zig’s standard library for HTTP, JSON parsing, and string allocation. The tool generates a useful artifact (changelogs) while demonstrating real-world concerns like credential handling, API integration, and Markdown formatting.

The source code is on GitHub at https://github.com/christianhelle/chlogr. If you need to automatically generate changelogs from GitHub, give it a try. Contributions and improvements are welcome!

This was one of several Zig projects I’ve built to learn the language. For other Zig tools, see HTTP File Runner, clocz, argiope, and ZigFaker. You might also be interested in how I automated changelog generation in GitHub Actions.

Christian Helle’s Blog

Reviving a 15 year old XNA Framework game with MonoGame

The prompt

Revisiting the original XNA codebase

Moving from XNA and Windows Phone to MonoGame and .NET 10

Extracting the puzzle rules into a real board model

Reworking the UI for desktop input

Persistence without Windows Phone isolated storage

Using GitHub Copilot CLI and Squad to do the rewrite

What stayed the same

Why MonoGame?

Final thoughts

From AI-Assisted Code Completion to Agentic Software Engineering

From novelty to daily habit

Why I hated chat-driven development

Copilot Agent Mode with Claude Sonnet changed the game

A tiny prompt can still go a long way

From assistant to agent

Running agents in parallel with /fleet

Building a persistent team with Squad

Fixing Refitter issues hands-free with YOLO mode

Where I am now

Generate a Changelog from GitHub Actions

What is chlogr?

What is the Changelog Generator Action?

Basic Usage

Understanding the Permissions

Conditional Commit with the changed Output

Advanced Usage Examples

Generating Changelog for a Different Repository

Filtering by Tag Range

Excluding Labels

Pinning chlogr Version

Multiple Changelogs in One Workflow

Real-World Example: Argiope

Integration Patterns

Generate Changelog on Release

Upload Changelog as Release Asset

Scheduled Changelog Updates

Multi-Platform Matrix Build

Features and Capabilities

Label Categorization

Link Generation

Token Resolution Strategies

Output File Handling

Troubleshooting and Tips

Token Authentication Errors

Rate Limiting

Empty or Missing Changelogs

Platform and Architecture Support

Permissions for Committing

Version Pinning Best Practices

Conclusion

ZigFaker - A Zig library to minimize unit testing ceremony

Installation

Supported Data Types

Example Usages

Anonymous Primitive Types

Anonymous Structs

Creating Collections

Realistic Fake Data

Nested Structs

Enums and Optionals

Reproducible Output

Building a web crawler and broken link detector in Zig

How it works

HTML Parsing

URL Normalization

HTTP Client

Command Line Interface

Report Generation

Usage

Distribution

Conclusion

Modernizing REST API Client Code Generator with the New Visual Studio Extensibility Model

The Evolution of an Extension

The “Dependency Hell” of In-Process Extensions

From “Custom Tools” to Explicit Commands

Architecture Comparison: Entry Points

Modernizing Commands and Async Execution

Conditional Commit with the `changed` Output

`guid()` - Generate UUID

`string()` - Generate Random String

`number()` - Generate Random Number

`base64_encode()` - Base64 Encoding

`upper()` - Convert to Uppercase

`lower()` - Convert to Lowercase

`name()` - Generate Full Name

`first_name()` - Generate First Name

`last_name()` - Generate Last Name

`address()` - Generate Address

`email()` - Generate Email Address

`job_title()` - Generate Job Title

`lorem_ipsum(n)` - Generate Lorem Ipsum Text

`getdate()` - Get Current Date

`gettime()` - Get Current Time

`getdatetime()` - Get Current Date and Time

`getutcdatetime()` - Get Current UTC Date and Time

Defining Query Records and `.kusto` Files