factorio-mod-workshop 0.1.0__py3-none-any.whl

fmw/help.py

@@ -0,0 +1,387 @@
+"""Prose help, shipped with the package.
+
+Kept here rather than in the repository's docs/ so that someone who installed
+via `uv tool install` - or an agent with no checkout - can read it. Each entry
+becomes a subcommand's argparse `description`, so `fmw <cmd> --help` is the
+single place this text appears; there is no parallel `help <cmd>` topic to
+drift out of step with it.
+"""
+
+OVERVIEW = """\
+fmw - Factorio Mod Workshop
+
+Turns mod portal activity into structured data you can triage, decide about and
+act on, across many mods at once.
+
+Three layers, deliberately separate:
+
+  cache/            what users actually said. Disposable, refetched in minutes.
+  threads/<mod>.yaml  what you decided about a conversation.
+  tracker/<mod>/    what you are doing about a problem. Code changes only.
+
+A typical session:
+
+  fmw sync                 fetch what is new
+  fmw inbox                see what needs a decision
+  fmw thread <id>          read one discussion in full
+  fmw mark <id> ...        record a judgement, or
+  fmw track new <id>       open a ticket when code must change
+  fmw testplan             batch verified-pending fixes into one game session
+
+Setup, once:
+
+  fmw init <path>          create a workspace
+                           then set FMW_WORKSPACE in your shell profile, or:
+  fmw launcher             put `fmw` on PATH, pinned to that workspace
+  fmw repo add <path>      register a directory holding your mods
+  fmw discover             find them, and read their portal metadata
+
+Every command takes --json for machine-readable output.
+
+fmw never writes to the mod portal: there is no write API, and replying to
+users is the maintainer's job. Only sync, discover and `thread --refresh` touch
+the network; everything else reads the local cache, so exploring costs nothing.
+
+Read any command's prose with `fmw <command> --help`. Two wider topics:
+`fmw help workspace` (file formats and every field value) and
+`fmw help workflow` (the loop, and the mistakes it prevents).
+`fmw help --all` prints everything at once.
+"""
+
+COMMANDS = {
+    "init": """\
+Create a workspace: the directory holding your registry, tickets, thread
+judgements and cache. Nothing is created implicitly, and the path is required -
+guessing which workspace was meant is worse than refusing.
+
+Copies a scaffold of documentation and examples. Existing files are never
+overwritten, so re-running it on an old workspace adds newly shipped files
+without touching your data. `fmw upgrade` refreshes the ones the tool owns.
+
+Afterwards: `fmw repo add <path>` for each directory holding your mods, then
+`fmw discover`.
+""",
+    "launcher": """\
+Install a small wrapper on your PATH that pins one workspace, so `fmw` works
+from any directory - typically from inside a mod repository - without exporting
+FMW_WORKSPACE by hand.
+
+Writes a POSIX `sh` script on Linux and macOS, a `.cmd` on Windows. Goes to the
+first conventional per-user bin directory already on your PATH - ~/.local/bin
+or ~/bin, or %APPDATA%\\uv\\bin on Windows - and prints the right command for
+your shell if none of them is.
+
+An FMW_WORKSPACE set in the environment still overrides it. Use --name for a
+second workspace, and re-run with --force after moving either directory, since
+the wrapper holds absolute paths.
+
+Refuses to run from an ephemeral `uvx` environment, whose path `uv cache prune`
+deletes. With `uv tool install`, `fmw` is already on PATH and you only need to
+export FMW_WORKSPACE.
+""",
+    "repo": """\
+Manage the directories `fmw discover` scans for mods. These are your mod
+checkouts - a monorepo, one repository per mod, or a mix.
+
+  fmw repo add ~/code/my-mods     register a directory and report what is in it
+  fmw repo list                   show them, with the mods found in each
+  fmw repo remove ~/code/old      stop scanning one
+
+Edits config.yaml in place, preserving its comments. Removing a repository does
+not remove mods already in the registry - delete those from mods.yaml if you
+want them gone.
+
+`fmw discover --scan DIR` scans a directory once without registering it.
+""",
+    "discover": """\
+Build the mod registry from two sources: your local checkouts and the portal.
+
+It does not read discussions - that is `fmw sync`. Here the portal is queried
+only through its metadata API, for published versions and download counts.
+
+Locally, walks each registered repository (see `fmw repo`) for info.json files -
+the manifest the game requires. Anything with a name and a version is a mod, so
+repo layout does not matter: a monorepo, one repo per mod, or a mix. Depth is 3
+levels by default; node_modules, .git, .venv and __pycache__ are skipped.
+
+Skips that you might not expect - unreadable JSON, a manifest without
+name/version, one mod name found twice - are reported rather than passed over
+silently. Only the depth limit and ignored directories are quiet.
+
+From the portal, adds published version, Factorio version, downloads and
+category. Mods you have locally but never published are marked and reported.
+--no-portal stays offline.
+
+Re-running merges: fields you own (maintained, notes, priority) are preserved,
+local facts refresh from the scan, and portal facts refresh only when a lookup
+happened - so --no-portal does not blank previously fetched data.
+""",
+    "mods": """\
+List the registry.
+
+Columns abbreviate: v = mod version, F = Factorio version, loc = your local
+checkout, mp = the mod portal, dl = downloads. Portal columns stay empty until
+`fmw discover` runs without --no-portal, and the command says so when they are.
+
+A `~` marks a mod whose local and published versions differ. It is a flag, not
+a diagnosis: unreleased work, an out-of-date checkout and a deliberate local
+edit are indistinguishable from the numbers. Ask the maintainer before changing
+such a checkout.
+
+`maintained` is yours to set: active, frozen or unknown. Frozen mods are
+skipped by sync, inbox and testplan unless --all.
+""",
+    "sync": """\
+Fetch discussions and report exactly what changed since the last run.
+
+The only command that hits the network, besides `discover` and
+`thread --refresh`. Idempotent: run it again and it prints nothing new. The
+first run fetches every thread and takes a few minutes for ~20 mods.
+
+Differences are appended to an append-only log, so `fmw changes --since` can
+replay them offline later.
+
+Also warns when a thread's title and its ticket disagree about being resolved -
+each direction means different unfinished work.
+
+Writes only to the cache. Your judgements and tickets are never touched by a
+network operation.
+""",
+    "changes": """\
+Replay changes recorded by earlier syncs, without touching the network.
+
+Two dates are shown per entry: `seen` is when fmw detected the change, `posted`
+is when the message was written. --since filters on `seen`, so after a first
+sync backfills months of history, everything carries today's detection date.
+""",
+    "inbox": """\
+Everything awaiting a decision, in one view: replies you owe, fixes awaiting
+your testing, open tickets, and threads nobody has triaged.
+
+Thread flags: T has a ticket, R you owe a reply, ! the maintainer judged the
+report mistaken.
+
+A thread leaves the inbox when a ticket cites it AND its conversation is
+settled, or when you record a judgement with `fmw mark`. Threads whose portal
+title already carries a resolution marker are hidden and counted separately;
+--all-threads shows them.
+
+Tickets stay listed while their thread is unsettled, because a ticket tracks
+the code change, not the conversation.
+""",
+    "mark": """\
+Record your judgement about a conversation - the alternative to opening a
+ticket. Most threads deserve one: a question you answered, a duplicate, a
+mistaken report, plain thanks. Tickets are for code changes.
+
+  --triage    pending | handled | ignored
+  --class     what the thread really is, regardless of its portal tag
+  --needs-response / --responded
+
+The portal's tag is a hint only. Reporters mislabel constantly: shy users file
+bugs as questions, careless ones file expected behaviour as errors.
+
+`--responded` is the only thing that clears a reply obligation - nothing infers
+it from you having read the thread.
+
+Bulk form: `--before YYYY-MM-DD [mods]` applies one judgement to every
+still-pending thread last active before that date, never overwriting a decision
+already recorded. Long-dormant threads accumulate faster than they can be read
+one at a time.
+""",
+    "threads": """\
+List a mod's threads with, under each, its id and author, your recorded
+judgement in brackets, and one line per ticket citing it with that ticket's
+kind and status.
+
+Tags are abbreviated bug, gen, idea, ann; --tag accepts either form.
+Resolution markers are not flagged separately because they are part of the
+title text.
+""",
+    "thread": """\
+Print one discussion as plain Markdown: title, tag, then every message with its
+author and exact timestamp.
+
+Reads from the cache, so it costs nothing; --refresh re-fetches first. A bare
+thread id is resolved against the cache to find its mod.
+
+Read the whole thread before concluding anything - the answer is often in a
+later reply, sometimes from the maintainer.
+""",
+    "search": """\
+Find threads and tickets mentioning a phrase, and answer "has anyone reported
+this before".
+
+Searches cached thread titles and message bodies, plus ticket titles and
+bodies. Prints the id, mod, title and the matching line with who wrote it, so
+results feed straight into `fmw thread <id>`.
+
+Grouping several reports of one problem into a single ticket is the workflow
+this exists for: add each thread to that ticket's sources rather than opening a
+second ticket.
+""",
+    "track": """\
+Tickets: things requiring a code change, `error` or `feature`. A thread needing
+an answer never becomes one - use `fmw mark`.
+
+`track new <thread-id>` takes the title from the thread, minus its resolution
+marker, and records the portal's tag. `--also <mod>` covers several mods, since
+some of these share code.
+
+Ids are random 6-hex, unique across mods, and never change, so retitling a
+ticket breaks no references. Edit the Markdown body directly to fill in
+Summary, Analysis, Resolution and Test plan.
+
+Statuses run new, needs-info, confirmed, in-progress, needs-testing, fixed,
+released - plus wontfix and duplicate. `needs-testing` means written but not
+verified in game, which is as far as an agent can take a fix on its own.
+""",
+    "testplan": """\
+Collect every ticket in `needs-testing` into one document, grouped by mod, with
+each ticket's Test plan section, the threads that reported it, and the checkout
+path.
+
+Each Factorio run costs real time, so fixes are batched and verified in a
+single session rather than one at a time. Tickets with no test plan written say
+so rather than appearing ready.
+
+After verifying, set each to `fixed`, then `released` once published - which
+raises a reply obligation on every thread the ticket cites.
+""",
+    "status": """\
+Workspace overview.
+
+`mods_in_default_scope` is what sync, inbox and testplan act on: everything not
+marked frozen. `mods_marked_active` counts only those you explicitly classified
+- the two differ, and both are useful.
+
+`awaiting_triage` uses exactly the definition `fmw inbox` lists, so the number
+here always matches the list you work from. Threads hidden because their portal
+title is already marked resolved are counted separately.
+
+Also warns when the workspace documentation predates the current schema, or
+when the workspace is not a git repository.
+""",
+    "upgrade": """\
+Bring a workspace to the current schema: refresh the documentation files the
+tool owns, rewrite `maintained` values onto the current vocabulary, and migrate
+tickets written by older versions.
+
+Your registry entries, tickets, thread judgements, cache and config.yaml keep
+their content. --dry-run reports what would change.
+
+Worth running after updating fmw: workspace docs are copied once at init and
+otherwise never change, so they can end up teaching a schema that no longer
+exists.
+""",
+}
+
+
+# Topics larger than one command. Same rule as COMMANDS: user-facing material
+# ships with the package, so it is readable without the repository. Anything
+# needed to *change* fmw rather than use it belongs in docs/ instead.
+TOPICS = {
+    "workspace": """\
+The workspace holds everything fmw knows. It lives outside the tool's own
+repository, at --workspace or $FMW_WORKSPACE; there is no implicit default,
+because guessing which one was meant is worse than refusing.
+
+  config.yaml            which directories to scan, Discord details   (you)
+  paths.yaml             where each mod is checked out on this machine
+  mods.yaml              the mod registry
+  threads/<mod>.yaml     your judgement about each conversation
+  tracker/<mod>/*.md     tickets
+  cache/<mod>/...        mirrored portal data - never hand-edit, sync overwrites it
+  notes/                 anything else
+
+Only config.yaml and paths.yaml are machine-specific, and `fmw init` writes a
+.gitignore excluding them. Everything else is portable, so a workspace can be a
+git repository several maintainers share: each copies config.example.yaml and
+runs `fmw discover` to generate their own paths.yaml.
+
+mods.yaml
+  maintained   active | frozen | unknown. Yours to set. Frozen mods are skipped
+               by sync, inbox and testplan unless --all; active and unknown are
+               in scope, so an unclassified mod is never silently ignored.
+               These words are chosen because YAML 1.1 turns bare yes/no into
+               booleans, which silently broke every comparison against them.
+  on_portal    true, false (a confirmed 404), or absent when never checked.
+  notes, priority, aliases   yours; preserved across discover runs.
+  Everything else is refreshed by `fmw discover`.
+
+tracker/<mod>/<id>-<slug>.md - YAML frontmatter, then Markdown
+  id        random 6-hex, unique across mods, never changes. References use it
+            alone, so retitling or renaming the file breaks nothing.
+  mods      list; the first is primary and decides the directory.
+  kind      error | feature. Tickets are code changes only.
+  status    new | needs-info | confirmed | in-progress | needs-testing |
+            fixed | released | wontfix | duplicate.
+            Open: the first five. needs-testing means written but unverified -
+            as far as an agent can take a fix. released raises a reply
+            obligation on every thread the ticket cites.
+  sources   portal:<24-hex-id> | discord:<url> | github:<url> | self.
+            Only portal: entries affect behaviour; they are how a thread is
+            known to be handled and how duplicates group into one ticket.
+  severity, affects, fixed_in, related, duplicate_of - convention, not enforced.
+  Body sections: Summary, Analysis, Resolution, Test plan.
+
+threads/<mod>.yaml - keyed by thread id
+  triage           pending | handled | ignored
+  needs_response   you owe the reporter a reply. Only `fmw mark --responded`
+                   clears it; nothing infers it from you having read anything.
+  class            error | feature | question | wrong | duplicate | chatter.
+                   Your reading, which the portal's tag is only a hint toward.
+  note, duplicate_of, announced (releases already told to the reporter)
+
+Only --kind and --status are validated, and only when set through the CLI.
+Nothing validates a file you edit by hand.
+""",
+    "workflow": """\
+The loop, and where each command fits.
+
+1. `fmw sync` - the only command that reaches the network besides discover and
+   `thread --refresh`. Prints exactly what changed; prints nothing when nothing
+   did. Safe to re-run.
+
+2. `fmw inbox` - everything awaiting a decision. Also `fmw status` for counts,
+   which use the same definition, so the dashboard matches the list.
+
+3. Read before deciding. `fmw thread <id>` prints a whole discussion; the
+   answer is often in a later reply, sometimes from the maintainer.
+   `fmw search <phrase>` finds every thread and ticket mentioning something -
+   run it before opening a ticket, so repeat reports join the existing one.
+
+4. Decide. Most threads need a judgement, not a ticket:
+
+     fmw mark <id> --triage handled --class question --note "answered inline"
+     fmw mark <id> --duplicate-of <other-thread-id>
+     fmw mark --before 2025-01-01 <mod> --triage handled     # bulk, never
+                                                             # overwrites a
+                                                             # recorded decision
+   Open a ticket only when code must change. Several reports of one problem
+   belong in one ticket with several sources, not several tickets.
+
+5. Fix, but do not claim it works. An agent cannot launch Factorio. Set
+   `status: needs-testing`, fill in the ticket's Test plan section, and leave
+   it. `fmw testplan` gathers every such ticket into one document so a batch is
+   verified in a single play session.
+
+6. After the maintainer confirms: `fixed`, then `released` once published.
+   Setting released makes every thread the ticket cites reappear under "You owe
+   a reply". Reply, then `fmw mark <id> --responded`.
+
+Notes that save mistakes:
+
+- The portal's thread tag is a hint, not a signal. Reporters mislabel
+  constantly: shy users file bugs as questions, careless ones file expected
+  behaviour as errors. Read the thread and set --class yourself.
+- Title markers are the opposite: [FIXED], (fixed), (Wrong) are written by the
+  maintainer and can be trusted. fmw reads them back automatically.
+- A `~` in `fmw mods` means local and published versions differ. Do not infer
+  why and do not "fix" it - unreleased work, an out-of-date checkout and a
+  deliberate local edit look identical. Ask.
+- Correlate a reported version against the mod's changelog before assuming a
+  bug still exists. Many reports are against old versions.
+- Never hand-edit cache/. The next sync overwrites it.
+""",
+}