Blog

A Slew of (Breaking) Fixes (MfGames Writing Tools)

2026-01-17T06:00:00Z

We've just pushed up a new version of mfgames-writing-js. Naturally, this started with the usual process of doing a little housekeeping, and bringing packages up to date.

The main focus was to fix two bugs:

Unfortunately, we had to make a breaking change and bumped the major version of some of the packages, which also requires at least a minor update to the other changes to pick up the new version ranges.

And then what followed was an embarassing set of NPM package updates as we tried to get everything working consistently and feeding into dependent projects like fedran-writing-setup-flake which is a mass setup scrip for all the writing projects on fedran.com.

Along the way, we also introduced --log-level support so mfgames-writing-format build wasn't quite as noisy.

Short Version

If you use mfgames-writing-js, update all your packages to the latest and things should Just Work™. If they don't, please don't hesitate to report an issue or contact Dulan

Pipeline Exclusions

Added an exclude to pipelines in the same pattern as the content elements:

contents:
  - element: chapter
    source: pipeline.md
    pipeline:
      - module: "@mfgames-writing/hyphen-pipeline"
        exclude:
          editions: [docx]

This caused a difficulty with an undocumented element in hyphen-pipeline which allowed for a regular expression to ignore certain words that caused problem with hyphenation. This was moved to exclude.regex.

contents:
  - element: chapter
    source: pipeline.md
    pipeline:
      - module: "@mfgames-writing/hyphen-pipeline"
        exclude:
          editions: [docx]
          regex: ["^bob$"]

Because this changed some projects in use, it was treated as a breaking change and bumped the version.

Section Breaks

When we write in Markdown, we always use *** for section breaks.

---
title: Chapter One
---

Something happened.

---

After the break.

However, proejcts like mfgames-writing-setup-flake use prettier which always converted the *** into --- which is also a proper Markdown rule (which we use as a section break in stories).

Due to interactions with SmartyPaths, those --- were helpfully turned into an em-dash (—). We put in a little patch code that an em-dash on a line by itself is considered a rule for section breaks and turned back into ---.

Output Directory

Another thing that we've done with mfgames-writing-setup-flake is put all the output files into the build/release folder to keep them out of the root directory of the repository. But there was a little but where .docx files couldn't handle that.

We fixed it.

Logging

Also, it was a little annoying having so much data that we added a --log-level to control output. It defaults to info but can also be trace, debug, info, warn, and error.

Updating Dependencies (MfGames Conventional Commit)

2025-12-05T06:00:00Z

Just a little maintenance update.

Updated the Nix flake from 25.05 to 25.11
Updated Rust to the 2025-12-05 nightly
Updated various dependency packages
Bumped the version to 0.3.0

Nothing really fancy, just housekeeping.

Making It Useful (MfGames Conventional Commit)

2025-08-12T05:00:00Z

We wrote mfgames-conventional-commits to solve a small itch of wanting to be able to calculate version numbers based on Conventional Commits but only for commits that touch specific directories. That way, a change to MfGames.IO would bump that version up but not touch the versioning for MfGames.Nitride in the same monorepo. For the most part, it was to allow the CIL projects to have different versions as they all had different lineages before they were combined.

As things go, we always intended to polish and expand on the tool but other things got in the way. But then D. Moonfire was working on Git For Authors and realized they didn't have a good solution for calculating version numbers of novels. Since we already had this tool, we spent a few days making it more useful and capable for single package projects and require less overhead to configure it.

Simplified Setup

The configuration file goes into //.config/mfgames-conventional-commit.json as usual, but setup has gotten significant easier. we added a defaults section that applies to every project along with substitutions for packages with {package} that allow each pack to have their own directories.

{
  "$schema": "https://mfgames.com/mfgames-conventional-commit-rs/schemas/v0.json",
  "defaults": {
    "tag_prefix": "{package}-",
    "directories": { "include": ["src/{package}"] },
    "files": { "include": ["src/{package}/**/*"] }
  },
  "packages": {
    "MfGames.Cryptography": {},
    "MfGames.DI.AutofacExtensions": {},
    "MfGames.Gallium": {},
    "MfGames.IO": {},
    // There is more here
    "MfGames.ToolBuilder.Tables": {}
  }
}

It used to be we had to have the tag_prefix and files elements in each one with a customization per project to include the path. Now, {package} can be used to substitute the package name and defaults to apply to any package that doesn't have settings underneath itself. In the future, we'll have some configuration that will scan the //src directory for the package names, but not this round.

Version Numbers

We also have two variants of version numbers based on usage. The first is the “flatten” version which calculates the most relevant major, minor, or patch version and applies it to the latest found tag. So if you have a “feat”, “fix”, “fix” on 1.0.0, it would be “1.1.0”. In contrast is the “detail” version which applies the version one at a time. So if you had the same “feat”, “fix”, “fix” on 1.0.0, the result would be “1.1.2”.

Most software projects seem to make a conscious decision to bump up the version. With semantic releases, the versioning is done on the pipeline. For a long time, we used “flattened” as the basic approach since that is what Semantic Release did. However, with novels and the like, sometimes they go out without the pipeline running and it is useful to make sure new versions show up; hence the use of “detail”.

This also resulted in a slightly different output for the mfgames-conventional-commit version command:

$ cd src/MfGames.IO
$ mfgames-conventional-commit version
 package_name  last_version  flatten_version  flatten_changed  detail_version  detail_changed
 MfGames.IO    2.7.0         2.7.0            false            2.7.0           false
$ mfgames-conventional-commit version --all | head -n 5
 package_name                        last_version  flatten_version  flatten_changed  detail_version  detail_changed
 MfGames.Cryptography                14.7.0        14.7.0           false            14.7.0          false
 MfGames.DI.AutofacExtensions                      0.0.1            true             0.0.1           true
 MfGames.Gallium                     3.6.0         3.6.0            false            3.6.0           false
 MfGames.IO                          2.7.0         2.7.0            false            2.7.0           false

Because we're fond of changing format as needed, so it can also dump a JSON or Markdown version. And all logging is sent to stderr, so piping can work properly.

$ mfgames-conventional-commit version --json | jq
[
  {
    "package_name": "MfGames.IO",
    "last_version": "2.7.0",
    "flatten_version": "2.7.0",
    "flatten_changed": false,
    "detail_version": "2.7.0",
    "detail_changed": false
  }
]
$ mfgames-conventional-commit version --all --format markdown | head -n 5

package_name	last_version	flatten_version	flatten_changed	detail_version	detail_changed
MfGames.Cryptography	14.7.0	14.7.0	false	14.7.0	false
MfGames.DI.AutofacExtensions		0.0.1	true	0.0.1	true
MfGames.Gallium	3.6.0	3.6.0	false	3.6.0	false
MfGames.IO	2.7.0	2.7.0	false	2.7.0	false
MfGames.Locking	2.5.1	2.5.1	false	2.5.1	false

Updates

Another useful feature is the ability to perform updates if the version number changed. This is used to define an updates element in the configuration file:

{
  "$schema": "https://mfgames.com/mfgames-conventional-commit-rs/schemas/v0.json",
  "defaults": {
    "updates": [
      { "script": "npm version {detail_version} --no-git-tag-version" },
      { "script": "git tag v{detail_version}" }
    ]
  }
}

As you can see from above, the command will change the NPM version and create a Git tag. If always_run is set to true, then it will run every time it is called, otherwise it will only run if the Git tag doesn't match the calculated tag.

The main reason for this is because then we don't have to write a hundred plugins for different systems. You can just write the script to do it, call another program, or just write some output. Anything a shell can do, this can do.

Inferred Package

One of the more annoying things is that we couldn't figure out the package name from the current context. For the most part, that didn't mean much since we could always provide --package package-name, but we found it useful enough that we made the tool figure out the patch from the directories attribute above. This also handles {package} substitutions, so it is generally useful.

Both the version and update commands also take an --all which means all packages in the project instead of --package package-name for an arbitrary package, or either of these to guess it from the directory.

Sane Defaults

Finally, we added a sane default if the //.config/mfgames-conventional-commit.json file is missing, or it doesn't have many settings. This assumes the entire directory is a single package called “default” and it uses a “vX.X.X” tag to represent versions.

Future Steps

This is a secondary project for us. Obvious, if we have an itch and it doesn't do something we want, we'll add it. If there are any issues that would be really useful or if you come up with something useful for the project (that is in scope), report or comment on it and we'll see about implementing it.

Introducing Fiss (Fiss)

2025-02-20T06:00:00Z

In a world where there are a lot of tools to manage tasks, this is one more. Fiss is a CLI-based tool that exposes issues from forges (such as Foregejo) in a task-centric interface. This tool is inspired by Taskwarrior and is designed from the ground up with the intent of using multiple forges, groups/organizations, and projects as the high-level organization.

Justification

There are a lot of tools that do the same thing, managing tasks. As well-designed or powerful as they are, the main reason for writing Fiss is that they didn't work the way we needed them too.

There Is More Than One Way To Do It

— Larry Wall

Fiss does, but isn't to say we haven't tried to find another alternative. We have, for many years and many attempts to find the “one perfect tool” for us.

Taskwarrior

Taskwarrior is very powerful, but it doesn't work well outside of the CLI. In our experience, the web services for sharing tasks across machines work fairly well, but are cumbersome to set up.

The support on Android, our current phone operating system, is relatively poor.

In many cases, the other services end up packaging Taskwarrior inside them to perform the various calculations because Taskwarrior is also very complex and not well documented. At least, it seems that way since there are not many Taskwarrior-compatible alternatives. Even the Android packages we found effectively said they packaged Taskwarrior inside them.

iCalendar

We love iCalendar (.ics) files. With our local NextCloud server, it is great for handling a lot of our common tasks.

Working with a Linux CLI and .ics is difficult. We've tried a number of different ways over the years and haven't found anything that works the way we want. Or consistently.

Introduction

Right now, this tool is barely alpha. It requires a lot of manual editing of the configuration file as documented on the website.

Adding a Server

Adding a server is pretty simple. A server has a short name, which is used by the tabular output and to reference the server.

export FISS_SERVER=mfgames
export SERVER_URL=https://src.mfgames.com
#TOKEN=the token from Forgejo
fiss server add -s $FISS_SERVER --url $SERVER_URL --token $TOKEN
fiss server add --url $SERVER_URL --token $TOKEN

It will also automatically pick up FISS_SERVER from the environment. Same for FISS_GROUP and FISS_PROJECT below.)

export FISS_SERVER=mfgames
fiss server add --url $SERVER_URL --token $TOKEN

It can be listed, not that it helps much.

$ fiss server list
 server   url                             forge    updated_seconds
 mfgames  https://src.mfgames.com/        forgejo  2025-02-15 13:15:41

All lists can be dumped as JSON:

$ fiss server list --json | jq
[
  {
    "server": "mfgames",
    "url": "https://src.mfgames.com/",
    "forge": "forgejo",
    "updated_seconds": "2025-02-14 18:04:54"
  }
]

They can also be dumped as Markdown:

$ fiss server list --markdown

server	url	forge	updated_seconds
mfgames	https://src.mfgames.com/	forgejo	2025-02-14 18:04:54

The reason servers are considered first-class is that we wrote Fiss to handle multiple forges at the same time. We have multiple Forgejo instances. Eventually, this tool will be expanded to also include iCalendar, SourceHut, GitLab, and GitHub. Potentially, one could have multiples of those also, so servers are part of the organization structure.

Groups

On a server, you have groups. Right now, users don't work yet, but groups are fine.

$ export FISS_GROUP=fiss
$ fiss group add -s $FISS_SERVER -g $FISS_GROUP

We decided to call the organizations and users “groups” because our “day job” uses “organizations” and it is really hard to spell that consistently while typing at speed. Using “groups” is relatively generic and is sufficient for our needs.

Projects

Projects are the third level of organization. Creatively, they are done the same way.

$ FISS_PROJECT=fiss
$ fiss project add -s $FISS_SERVER -g $FISS_GROUP -p $FISS_PROJECT

Caching

To avoid overloading the forges, we cache the issues. In the future, we periodically will refresh the data, pick up new issues, close others. Right now, you have to manually pull in the data.

fiss cache sync

⚠ Since there isn't a lot of elegance at this point, this will pick up all projects underneath a group and also download every single issue from those projects. That includes closed and open. So, it would not be a good idea to point this at any project that has a large number of issues.

There is also going to be controls for automatically subscribing to new projects, so you can choose to get all of them, or only require specific ones.

Issues

Once everything is synced, then the commands are pretty simple. To list issues:

fiss list -s $FISS_SERVER -g $FISS_GROUP -p $FISS_PROJECT

If the command is run inside a Git repository (any inner directory can work, it will find the Git root), it will attempt to pick up the server, group, and project from the remotes. Also, if there is a distinct name for a project, then -p $FISS_PROJECT would be sufficient.

If you want to list all projects inside a Git repository, the list command supports globbing for servers, groups, and slugs. This means fiss list -p '*' will show all projects no matter where you are in your directory structure. Also, multiple globbing can be done with colons, such fiss list -p fiss:mfgames-cil will list all fiss and mfgames-cil projects.

From this point on, we're going to assume you are in the Git directory or have FISS_SERVER, FISS_GROUP, and FISS_PROJECT set appropriately.

fiss list

Creating a new issue also relatively simple and there really isn't that much. The rest of the commands are assuming you are in a Git directory, or you exported

$ fiss add -t "Name of project"

This creates an issue. Right now, it just says nothing but it will eventually give you a useful message or at least emit the issue number.

There are commands to open and close tickets using -i or --issue with the issue number.

fiss issue close -i 3
fiss issue open -i 3

Example

So far, even at this basic state, it is fairly functional.

cd fiss
fiss list --markdown

id	title	state
mfgames/fiss/fiss/6	Cache foregejo API handle	open
mfgames/fiss/fiss/7	Refresh servers, groups, and projects periodically	open
mfgames/fiss/fiss/8	Show progress while syncing with server	open
mfgames/fiss/fiss/9	Teach ‘cache sync’ to only sync certain projects	open
mfgames/fiss/fiss/10	Show information after creating a new issue	open
mfgames/fiss/fiss/11	Allow for –body/-b to edit the body text	open
mfgames/fiss/fiss/12	Update to new version of foregejo API	open
mfgames/fiss/fiss/13	Implement subscriptions	open
mfgames/fiss/fiss/14	Do not show closed issues by default	open
mfgames/fiss/fiss/15	Do not show archived projects by default	open
mfgames/fiss/fiss/16	Get flake working as input for another flake	open

You can also see this list on our forge.

Future

So, we think this tool has potential. We'll be using it and improving it slowly as we find pain points or things where it doesn't work. At minimum, the goals are:

Add, create, and list tags on issues
Implement milestones
Implement sub-projects
Be able to edit other elements of the item (fiss edit -i 3)
Be able to open up the page from the CLI (fiss web -i 3)
Get it working properly with NixOS flakes
Be more elegant in retrieving issues
Implement the subscription control so we can decide to include 100s of projects automatically

Moved Repository to MfGames (MfGames Writing Tools)

2025-01-12T06:00:00Z

It's been a few years and this project has moved homes a few times. We realized in the last day that we haven't been paying attention to where this project was housed compared to when we abandoned GitLab because of their enshittification.

The current home for mfgames-writing-js is now on src.mfgames.com and it now has a fancier home page.

We are going to spend a little time spurcing up the library, bringing it to a modern version of TypeScript, and infrastructure. This will be considered a break changing since the underlying libraries have jumped significantly in version.

Updated to NixOS 25.05 (MfGames Writing Setup Flake)

2025-01-11T06:00:00Z

We've updated the flake to be based off NixOS 25.05 and the latest version of mfgames-project-setup-flake.

Updated to NixOS 24.11 (MfGames Writing Setup Flake)

2025-01-11T06:00:00Z

An occasional chores, we've updated the flake to be based off NixOS 24.11. From our understanding, the flake input could always be changed but this sets up a nice default using the current, non-deprecated version of NixOS.

Along with this, we've also updated to the latest version of mfgames-project-setup-flake which does the same thing (and copies the same first paragraph as this post).

Update to NixOS 24.11 (MfGames Project Setup Flake)

2025-01-10T06:00:00Z

This came with a couple surprising changes, mostly in behavior from our tools. In specific, treefmt got a lot noisier with 24.11 when it came to unknown files in the repository (like .php files we we don't have set up). Modifications were made to the linked treefmt.toml file to not report those to avoid a wall of text when there were a lot of them.

Update to NixOS 25.05 and more (MfGames Project Setup Flake)

2025-01-10T06:00:00Z

Well, it's about time to update the flake to NixOS 25.05 just for general maintenance. There wasn't really anything special with this one, but we did have a couple minor and one big change:

The conform settings did not put the scopes into the right place
After experiencs, we added .cache to .gitignore
When Rust is enabled, add target to .gitignore

The other big change is we are adding mfgames-conventional-commit as part of the flake. That way, we have a consistent method for updating version numbers based on conventional commits and it plays well with the intent we have with conform.

Deprecating Priduck (Priduck Color Theme)

2024-12-20T06:00:00Z

Sometimes, a path of development leads to a dead end. In this case, Priduck was written to create a more dynamic color theme based on a single color that was spread evenly around the color wheel using LCH colors.

The idea was to support the bi-chromatic covers of Fedran which every point-of-view was assigned a color and it used a complementary color for accents. In our heads, it would create a striking display and would clearly identify books within a series easily.

It was also too limiting. The current plan is to use a more static color scheme, in specific Reasonable Colors and allow a full gamut of colors on the book covers.

That decision meant that this project doesn't make sense anymore. That isn't to say it doesn't have useful components in it, so it isn't going to be deleted from the repository.

It might be resurrected in the future, it might not. We also a little vain, so if someone finds a compelling need to use these things and doesn't want to fork it (please do), then things might change.

But for the time being, development on this project has ceased.

Changed the default .NET formatter (MfGames Project Setup Flake)

2024-08-07T05:00:00Z

When we first introduced the .NET formatter for C# files, we picked csharpier because it was a lot faster than dotnet format. Since then, the opinionated formatting that came with csharpier was getting in the way of our style and along with conflcits with ReSharper.

The latest is breaking change that switches the default formatter out but retains the csharpier formatting for those who want it. To put it back:

config = inputs.mfgames-project-setup.lib.mkConfig {
    inherit system pkgs;
    dotnet.enable = true;
    dotnet.csharpier = true;
    dotnet.format = false; # Defaults to false, so don't need it.
};

To use dotnet format, the setup would be:

config = inputs.mfgames-project-setup.lib.mkConfig {
    inherit system pkgs;
    dotnet.enable = true;
    dotnet.format = true;
};

Create iCalendar Files with Nitride (MfGames .NET Libraries)

2024-06-01T05:00:00Z

One of the more useful features in previous versions of Dylan's static site generators was the ability to create an iCalendar file of the posts, both past and future. It wasn't only just to see little entries pop up for the dopamine rush, but also to give them a head's up when a new chapter for Fedran needs to be written or its been a few months since a blog post has been written.

We use iCalendar because it's a solid standard format that can easily be added into Nextcloud, put on a phone, or otherwise used anywhere to keep it in mind.

(Technicaly, it could also be used to create task lists for sites that are missing links or other things but out of scope for this iteration).

We put this into the MfGames.Nitride.Temporal even though it adds an extra dependency (Ical.Net) because it is a relatively small feature and it hit that ratio of package management verses three additional classes. Like the rest of the temporal packages, this built to use Noda.Time for coordinating times.

The documentation has some notes on how to include and use it inside a Nitride project.

New Entity Constructor

We also added new constructor to MfGames.Gallium.Entity that allows multiple components to be set as part of the constructor.

// These are all the same.
var entity1 = new Entity();
entity1 = entity1.Add("bob");
entity1 = entity1.Add(13);

var entity2 = new Entity().Add("bob").Add(13);

var entity3 = new Entity().SetAll("bob", 13);

// These are the new features.
var entity4 = new Entity("bob", 13);

var entity5 = new Entity(13, "bob");

It seemed like a no-brainer, mainly because it is a pattern we use a lot in the code, but Dylan finds that the formatting is less than “pretty” when it comes to multi-line chaining operations.

var notPretty = new Entity(
    "bob",
    13,
    instant,
    path)
    .AddTextContent(content);

var pretty = new Entity()
    .SetAll(
        "bob",
        13,
        instant,
        path)
    .AddTextContent(content);

Either work though, so it will end up reducing some of the clutter for common use cases.

Refactoring Again (Priduck Color Theme)

2024-05-09T05:00:00Z

Originally, when this theme was created, it made sense to create two separate packages to provide the theme, one for the CSS files themselves and the other for a CLI to generate the source files.

These we needed to generate GPL palettes for Inkscape and that specific abstraction started to crumble. The result is that we merged the two Priduck repositories together and made it a single theme, with the intent that one would generate the files they want instead of a tiny package that just provided a single CSS variables version.

This will also allow for the generation of character-specific stylesheets over at Fedran not to mention the book covers over there.

The CLI

The CLI is pretty simple, a verb-based Node script that installs into the node_modules/.bin folder as usual:

$ priduck
priduck <cmd> [args]

Commands:
  priduck css      Generate CSS files
  priduck palette  Generate palette files

Options:
  --version  Show version number                                       [boolean]
  --help     Show help                                                 [boolean]

Not enough non-option arguments: got 0, need at least 2

The three basic commands are:

priduck css variables [--output /path/style.css] to generate the CSS variables CSS file.
priduck css mixin to combine CSS fragments files instead a combination of media queries and data attributes for supporting prefers-color-scheme and prefers-contrast options.
priduck palette gpl --hue [--output example.gpl] which generates a hue-specific palette file for GNU Imp and Inkscape.

Documentation

Along the process, a project can never be done if it isn't documented, so we wrote some documentation. It gives the general gist of the tool. We'll expand on it some more “someday.”