From 61c17ca585edf32ae0050921701f16c2f7e98f07 Mon Sep 17 00:00:00 2001 From: sneak Date: Thu, 18 Dec 2025 01:29:56 -0800 Subject: [PATCH] Normalize markdown formatting in documentation - Use consistent dash-style bullet points - Remove trailing whitespace - Add missing blank lines between sections - Add trailing newline to README.md --- CLAUDE.md | 20 ++++++++++---------- README.md | 36 +++++++++++++++++++++++------------- 2 files changed, 33 insertions(+), 23 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f4556e2..913107d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,20 +1,20 @@ # Important Rules -* when fixing a bug, write a failing test FIRST. only after the test fails, write - the code to fix the bug. then ensure the test passes. leave the test in - place and commit it with the bugfix. don't run shell commands to test - bugfixes or reproduce bugs. write tests! +- when fixing a bug, write a failing test FIRST. only after the test fails, write + the code to fix the bug. then ensure the test passes. leave the test in + place and commit it with the bugfix. don't run shell commands to test + bugfixes or reproduce bugs. write tests! -* never, ever mention claude or anthropic in commit messages. do not use attribution +- never, ever mention claude or anthropic in commit messages. do not use attribution -* after each change, run "make fmt". +- after each change, run "make fmt". -* after each change, run "make test" and ensure all tests pass. +- after each change, run "make test" and ensure all tests pass. -* after each change, run "make lint" and ensure no linting errors. fix any +- after each change, run "make lint" and ensure no linting errors. fix any you find, one by one. -* after each change, commit the files you've changed. push after +- after each change, commit the files you've changed. push after committing. -* NEVER use `git add -A`. always add only individual files that you've changed. +- NEVER use `git add -A`. always add only individual files that you've changed. diff --git a/README.md b/README.md index 8ea82c9..3882063 100644 --- a/README.md +++ b/README.md @@ -3,25 +3,25 @@ [mfer](https://git.eeqj.de/sneak/mfer) is a reference implementation library and thin wrapper command-line utility written in [Go](https://golang.org) and first published in 2022 under the [WTFPL](https://wtfpl.net) (public -domain) license. It specifies and generates `.mf` manifest files over a +domain) license. It specifies and generates `.mf` manifest files over a directory tree of files to encapsulate metadata about them (such as cryptographic checksums or signatures over same) to aid in archiving, -downloading, and streaming, or mirroring. The manifest files' data is +downloading, and streaming, or mirroring. The manifest files' data is serialized with Google's [protobuf serialization -format](https://developers.google.com/protocol-buffers). The structure of +format](https://developers.google.com/protocol-buffers). The structure of these files can be found [in the format specification](https://git.eeqj.de/sneak/mfer/src/branch/main/mfer/mf.proto) which is included in the [project repository](https://git.eeqj.de/sneak/mfer). The current version is pre-1.0 and while the repo was published in 2022, -there has not yet been any versioned release. [SemVer](https://semver.org) +there has not yet been any versioned release. [SemVer](https://semver.org) will be used for releases. This project was started by [@sneak](https://sneak.berlin) to scratch an itch in 2022 and is currently a one-person effort, though the goal is for this to emerge as a de-facto standard and be incorporated into other -software. A compatible javascript library is planned. +software. A compatible javascript library is planned. # Phases @@ -57,6 +57,7 @@ Reading file contents and computing cryptographic hashes for manifest generation ## cmd/mfer/ ### main.go + - **Variables** - `Appname string` - Application name - `Version string` - Version string (set at build time) @@ -65,12 +66,14 @@ Reading file contents and computing cryptographic hashes for manifest generation ## internal/cli/ ### entry.go + - **Variables** - `NO_COLOR bool` - Disables color output when NO_COLOR env var is set - **Functions** - `Run(Appname, Version, Gitrev string) int` - Main entry point for the CLI ### mfer.go + - **Types** - `CLIApp struct` - Main CLI application container - **Methods** @@ -79,6 +82,7 @@ Reading file contents and computing cryptographic hashes for manifest generation ## internal/log/ ### log.go + - **Functions** - `Init()` - Initializes the logger - `Info(arg string)` - Logs at info level @@ -99,6 +103,7 @@ Reading file contents and computing cryptographic hashes for manifest generation ## internal/scanner/ ### scanner.go + - **Types** - `Options struct` - Options for scanner behavior - `IncludeDotfiles bool` - Include dot (hidden) files (excluded by default) @@ -138,6 +143,7 @@ Reading file contents and computing cryptographic hashes for manifest generation ## internal/checker/ ### checker.go + - **Types** - `Result struct` - Outcome of checking a single file - `Path string` - File path from manifest @@ -169,12 +175,14 @@ Reading file contents and computing cryptographic hashes for manifest generation ## mfer/ ### manifest.go + - **Types** - `manifest struct` - Internal representation of a manifest file - **Methods** - `(*manifest) Files() []*MFFilePath` - Returns all file entries from a loaded manifest ### builder.go + - **Types** - `FileHashProgress struct` - Progress info during file hashing (BytesRead int64) - `Builder struct` - Constructs manifests by adding files one at a time @@ -182,20 +190,23 @@ Reading file contents and computing cryptographic hashes for manifest generation - `NewBuilder() *Builder` - Creates a new Builder - **Methods** - `(*Builder) AddFile(path string, size int64, mtime time.Time, reader io.Reader, progress chan<- FileHashProgress) (int64, error)` - Reads file, computes hash, adds to manifest - - `(*Builder) AddFileWithHash(path string, size int64, mtime time.Time, hash []byte)` - Adds file with pre-computed hash + - `(*Builder) AddFileWithHash(path string, size int64, mtime time.Time, hash []byte) error` - Adds file with pre-computed hash - `(*Builder) FileCount() int` - Returns number of files added - `(*Builder) Build(w io.Writer) error` - Finalizes and writes manifest ### serialize.go + - **Constants** - `MAGIC string` - Magic bytes prefix for manifest files ("ZNAVSRFG") ### deserialize.go + - **Functions** - `NewManifestFromReader(input io.Reader) (*manifest, error)` - Reads and parses manifest from io.Reader - `NewManifestFromFile(fs afero.Fs, path string) (*manifest, error)` - Reads and parses manifest from file path ### mf.pb.go (generated from mf.proto) + - **Enum Types** - `MFFileOuter_Version` - Outer file format version - `MFFileOuter_VERSION_NONE` @@ -241,19 +252,18 @@ Reading file contents and computing cryptographic hashes for manifest generation # Participation The community is as yet nonexistent so there are no defined policies or -norms yet. Primary development happens on a privately-run Gitea instance at +norms yet. Primary development happens on a privately-run Gitea instance at [https://git.eeqj.de/sneak/mfer](https://git.eeqj.de/sneak/mfer) and issues are [tracked there](https://git.eeqj.de/sneak/mfer/issues). Changes must always be formatted with a standard `go fmt`, syntactically valid, and must pass the linting defined in the repository (presently only -the `golangci-lint` defaults), which can be run with a `make lint`. The +the `golangci-lint` defaults), which can be run with a `make lint`. The `main` branch is protected and all changes must be made via [pull requests](https://git.eeqj.de/sneak/mfer/pulls) and pass CI to be merged. Any changes submitted to this project must also be [WTFPL-licensed](https://wtfpl.net) to be considered. - # Problem Statement Given a plain URL, there is no standard way to safely and programmatically @@ -424,13 +434,13 @@ desired username for an account on this Gitea instance. ## Links -* Repo: [https://git.eeqj.de/sneak/mfer](https://git.eeqj.de/sneak/mfer) -* Issues: [https://git.eeqj.de/sneak/mfer/issues](https://git.eeqj.de/sneak/mfer/issues) +- Repo: [https://git.eeqj.de/sneak/mfer](https://git.eeqj.de/sneak/mfer) +- Issues: [https://git.eeqj.de/sneak/mfer/issues](https://git.eeqj.de/sneak/mfer/issues) # Authors -* [@sneak <sneak@sneak.berlin>](mailto:sneak@sneak.berlin) +- [@sneak <sneak@sneak.berlin>](mailto:sneak@sneak.berlin) # License -* [WTFPL](https://wtfpl.net) \ No newline at end of file +- [WTFPL](https://wtfpl.net)