Metadata-Version: 2.5
Name: factorio-mod-workshop
Version: 0.1.1
Summary: A workshop for maintaining Factorio mods: portal discussions, triage, tickets and release follow-up
Project-URL: Homepage, https://github.com/AivanF/factorio-mod-workshop
Project-URL: Repository, https://github.com/AivanF/factorio-mod-workshop
Project-URL: Issues, https://github.com/AivanF/factorio-mod-workshop/issues
Author: AivanF
License-File: LICENSE
Keywords: cli,factorio,issue-tracker,maintenance,mod-portal,modding
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

![FMW logo](https://raw.githubusercontent.com/AivanF/factorio-mod-workshop/main/docs/logo/FMW-blueprint.jpg)

[![PyPI](https://img.shields.io/pypi/v/factorio-mod-workshop?label=PyPI)](https://pypi.org/project/factorio-mod-workshop/)
[![License](https://img.shields.io/github/license/AivanF/factorio-mod-workshop)](LICENSE)
[![AivanF Discord](https://img.shields.io/badge/Discord-Community-blue)](https://discord.gg/7QCXn35mU5)

# Factorio Mod Workshop

**A maintainer's workbench for Factorio mods.** Keeps track of everything you owe your mods — bugs to fix, features you meant to build, questions to answer — across every mod you own, from one place.

Built for maintainers with more mods than time, and for the AI agents helping them.

```
$ fmw inbox
== You owe a reply (1) ==
  TR  [bug  ] 2026-08-31   0r  Incompatibility with my favorite mod
      6a93b26dead0beef42cd3c3b  WH40k-Titans
      fix shipped, reporter not told - released: 3d33eb

== Awaiting your testing (2) - run `fmw testplan` ==
  c341fd  WH40k-Titans: Error loading mods after update

== Threads awaiting triage (123, 28 hidden as resolved on the portal) ==
```

## 1. What it holds

**Tickets** are the centre: a bug to fix, a feature to build, an idea worth keeping. They stand on their own — many begin as a thought of yours or a message on Discord, and never touch the mod portal at all.

```sh
fmw track new Lightning "Configurable strike frequency" --kind feature
fmw track new WH40k-Titans "Pathfinding stalls on cliffs" --source discord:<url>
fmw track new 6a963b26...                    # or from a portal thread, title filled in
```

A ticket carries its analysis, the fix, and a test plan for when you next launch the game. One ticket can cover several mods, because large mods share code.

**Discussions** are one input among several — but the noisiest, and the only one with no tooling of its own.

## 2. Why the portal needs help

The mod portal has no API for discussions, no notion of a thread being handled, and no quick way to tell that four reports describe one bug. So a popular mod accumulates a hundred conversations you can neither search nor close, and every visit starts from scratch.

`fmw` gives that a memory.

- **Nothing gets lost.** Every discussion is mirrored locally with exact timestamps, so each sync reports precisely what is new. Repeat runs print nothing when nothing happened.
- **Duplicates become one thing.** `fmw search` finds every thread describing a problem; one ticket cites them all — across mods, since large mods share code.
- **Most threads never need a ticket.** A question you answered, a duplicate, a mistaken report: record the judgement and it leaves your inbox. Tickets stay for code changes.
- **Shipping closes the loop.** Mark a fix released and every thread that reported it comes back, once, asking you to tell the reporter.
- **Agents stop where they must.** An AI can triage, group and write fixes — it cannot launch Factorio. Fixes park in `needs-testing` and `fmw testplan` batches them into a single play session.
- **Your data is yours.** Plain YAML and Markdown in a directory you choose, outside this repo, ready to be its own git repository.

## 3. Install
### 3.1. As a User

Install `uv` if you don't have it yet:

| OS | |
| --- | --- |
| MacOS & Linux | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| Windows | `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"` |

Install `fmw` using `uv`:

```sh
uv tool install git+https://github.com/AivanF/factorio-mod-workshop
```

Create your workspace repository:

```sh
fmw init ~/factorio-workspace
```

Optional but recommended: specify the workspace location globally once, by setting `FMW_WORKSPACE` in your shell profile:

| Shell | |
| --- | --- |
| bash | `echo 'export FMW_WORKSPACE=~/factorio-workspace' >> ~/.bashrc` |
| zsh | `echo 'export FMW_WORKSPACE=~/factorio-workspace' >> ~/.zshrc` |
| fish | `set -Ux FMW_WORKSPACE ~/factorio-workspace` |
| PowerShell | `setx FMW_WORKSPACE "$HOME\factorio-workspace"` |

Or skip it and pass `FMW_WORKSPACE` env var or `--workspace <path>` arg to any command.

Finally, point it at your mods and pull everything in:

```sh
fmw repo add ~/code/my-factorio-mods   # a monorepo, or one repo per mod
fmw discover                           # find them, read their portal metadata
fmw sync --all                         # fetch every discussion
```

### 3.2. Working on FMW itself

```sh
git clone https://github.com/AivanF/factorio-mod-workshop && cd factorio-mod-workshop
uv venv && uv pip install -e .
./.venv/bin/fmw init ~/factorio-workspace
./.venv/bin/fmw launcher --workspace ~/factorio-workspace
```

`fmw launcher` installs a small wrapper on your PATH that pins a workspace, so `fmw` works from any directory without setting anything — a POSIX `sh` script on Linux and macOS, a `.cmd` on Windows. Edits to the source take effect immediately.

Requires Python 3.10+. Developed on macOS and used on Linux; the Windows paths are implemented but untested — reports welcome.

## 4. Daily loop

```sh
fmw inbox                  # what needs a decision
fmw track new <mod> "..."  # capture a bug, a feature, an idea
fmw sync                   # pull in what users posted
fmw thread <id>            # read one discussion
fmw mark <id> ...          # settle a conversation without a ticket
fmw testplan               # batch pending fixes into one play session
fmw status                 # show workspace path & FMW statistics
```

Run it from inside a mod repository and it scopes itself to that mod, saying which one it picked.

## 5. Help

Every command carries its own prose — no need for this page or a checkout:

```sh
fmw help            # overview and the daily loop
fmw sync --help     # what a command is for, and its gotchas
fmw help --all      # everything at once, for agents
```

Every command also takes `--json`.

## 6. Design

Three layers, deliberately separate:

| | |
| --- | --- |
| `cache/` | what users actually said — disposable, refetched in minutes |
| `threads/<mod>.yaml` | what you decided about a conversation |
| `tracker/<mod>/*.md` | the work itself — tickets, whatever their origin |

A network sync writes only to the first, so it can never overwrite a judgement. `fmw` never writes to the mod portal: there is no write API, and replying is the maintainer's job.

## 7. Documentation

**Using `fmw`** — everything ships with the package, so it works from a `uv tool install` with no checkout:

```sh
fmw help workspace   # file formats and every field value
fmw help workflow    # the loop, and the mistakes it prevents
fmw help --all       # the lot, in one call
```

**Working on `fmw`:**

- [CHANGELOG.md](CHANGELOG.md) — what changed in each release
- [docs/portal-notes.md](docs/portal-notes.md) — how the mod portal behaves, including its traps
- [CLAUDE.md](CLAUDE.md) — conventions for coding agents changing this repo
