From bd3ba1bdbf67bdb12a247fb1eaa25787f41ad31d Mon Sep 17 00:00:00 2001 From: Awiteb Date: Fri, 1 Aug 2025 18:46:02 +0000 Subject: [PATCH] docs: n34 book Signed-off-by: Awiteb --- .gitignore | 1 + book.toml | 10 + docs/SUMMARY.md | 33 +++ docs/commands.md | 63 ++++++ docs/config/README.md | 7 + docs/config/bunker.md | 27 +++ docs/config/keyring.md | 27 +++ docs/config/pow.md | 20 ++ docs/config/relays.md | 21 ++ docs/index.html | 449 +++++++++++++++++++++++++++++++++++++++++ docs/issue/README.md | 15 ++ docs/issue/close.md | 19 ++ docs/issue/list.md | 19 ++ docs/issue/new.md | 29 +++ docs/issue/reopen.md | 19 ++ docs/issue/resolve.md | 18 ++ docs/issue/view.md | 19 ++ docs/patch/README.md | 21 ++ docs/patch/apply.md | 30 +++ docs/patch/close.md | 20 ++ docs/patch/draft.md | 19 ++ docs/patch/fetch.md | 21 ++ docs/patch/list.md | 20 ++ docs/patch/merge.md | 28 +++ docs/patch/reopen.md | 20 ++ docs/patch/send.md | 22 ++ docs/reply.md | 28 +++ docs/repo/README.md | 4 + docs/repo/announce.md | 32 +++ docs/repo/view.md | 20 ++ docs/sets/README.md | 11 + docs/sets/new.md | 25 +++ docs/sets/remove.md | 24 +++ docs/sets/show.md | 17 ++ docs/sets/update.md | 25 +++ flake.nix | 1 + justfile | 20 +- 37 files changed, 1203 insertions(+), 1 deletion(-) create mode 100644 book.toml create mode 100644 docs/SUMMARY.md create mode 100644 docs/commands.md create mode 100644 docs/config/README.md create mode 100644 docs/config/bunker.md create mode 100644 docs/config/keyring.md create mode 100644 docs/config/pow.md create mode 100644 docs/config/relays.md create mode 100644 docs/index.html create mode 100644 docs/issue/README.md create mode 100644 docs/issue/close.md create mode 100644 docs/issue/list.md create mode 100644 docs/issue/new.md create mode 100644 docs/issue/reopen.md create mode 100644 docs/issue/resolve.md create mode 100644 docs/issue/view.md create mode 100644 docs/patch/README.md create mode 100644 docs/patch/apply.md create mode 100644 docs/patch/close.md create mode 100644 docs/patch/draft.md create mode 100644 docs/patch/fetch.md create mode 100644 docs/patch/list.md create mode 100644 docs/patch/merge.md create mode 100644 docs/patch/reopen.md create mode 100644 docs/patch/send.md create mode 100644 docs/reply.md create mode 100644 docs/repo/README.md create mode 100644 docs/repo/announce.md create mode 100644 docs/repo/view.md create mode 100644 docs/sets/README.md create mode 100644 docs/sets/new.md create mode 100644 docs/sets/remove.md create mode 100644 docs/sets/show.md create mode 100644 docs/sets/update.md diff --git a/.gitignore b/.gitignore index ea8c4bf..11e2b4a 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ /target +/book diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..85a7aad --- /dev/null +++ b/book.toml @@ -0,0 +1,10 @@ +[book] +authors = ["Awiteb"] +language = "en" +multilingual = false +src = "docs" +title = "n34 documentation" + +[output.html] +git-repository-icon = "fa-git" +git-repository-url = "https://git.4rs.nl/awiteb/n34.git" diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..aa52e77 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,33 @@ +# n34 documentation + +- [Command Line Usage](commands.md) + - [Managing Repository and Relay Sets](sets/README.md) + - [Create a Set](sets/new.md) + - [Modify a Set](sets/update.md) + - [Show Sets](sets/show.md) + - [Remove a Set](sets/remove.md) + - [Manage Configuration](config/README.md) + - [Default PoW Difficulty](config/pow.md) + - [Fallback Relays](config/relays.md) + - [NIP-46 Bunker](config/bunker.md) + - [Secret Key Keyring](config/keyring.md) + - [Manage Repositories](repo/README.md) + - [Broadcast and Update a Git Repository](repo/announce.md) + - [View Git Repository Details](repo/view.md) + - [Issue Management](issue/README.md) + - [Create an Issue](issue/new.md) + - [View an Issue By ID](issue/view.md) + - [Reopen a Closed Issue](issue/reopen.md) + - [Closes an Open Issue](issue/close.md) + - [Resolves an Issue](issue/resolve.md) + - [List Repositories Issues](issue/list.md) + - [Patch Management](patch/README.md) + - [Send Patches to a Repository](patch/send.md) + - [Fetch a Patch By ID](patch/fetch.md) + - [Reopens a Closed or Drafted Patch](patch/reopen.md) + - [Closes an Open or Drafted Patch](patch/close.md) + - [Draft an Open Patch](patch/draft.md) + - [Apply an Open Patch](patch/apply.md) + - [Merge an Open Patch](patch/merge.md) + - [List Repositories Patches](patch/list.md) + - [Reply to Issues and Patches](reply.md) diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..c7f28f4 --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,63 @@ +# Command-Line Usage + +## Options + +The `n34` command-line tool accepts the following options: + +- `-s`, `--secret-key`: Your Nostr secret key (in `nsec` format), used for + signing events. +- `-b`, `--bunker-url`: The URL of a NIP-46 bunker service used for remote + signing of events. +- `-r`, `--relays`: A relay to read from and write to. This option can be + specified multiple times to connect to several relays. +- `--pow`: Sets the Proof of Work difficulty required when creating events. +- `--config`: Specifies a custom path to the configuration file (Default: + `$HOME/.config/n34/config.toml`). +- `-v`, `--verbose...`: Increases the logging verbosity. Can be used multiple + times for more detail (e.g., `-v`, `-vv`). + +**Note:** The `--secret-key` and `--bunker-url` options are mutually exclusive. +You must provide exactly one signing method. + +## Multiple Repositories + +Commands that interact with a repository, such as submitting an issue or a +patch, can accept multiple repository addresses (`naddr`). This feature is +useful for projects with multiple maintainers who each have their own repository +fork. + +> **Important:** When you provide multiple repositories, `n34` does not +create a separate issue or patch for each one. Instead, it creates a single +event that references all of the specified repositories. + +## The `nostr-address` File + +The `nostr-address` file is a plain text file that stores a list of project +repository addresses. This allows the `n34` to find and use them +without requiring you to enter the addresses manually. + +### Format + +- Each line must contain a single addressable event coordinate `naddr` which is + the repository address. +- Lines beginning with a `#` are treated as comments and are ignored. +- Empty lines are also ignored. + +## Passing repositories + +By default, `n34` will look for a `nostr-address` file to extract repositories +from it. This is why repositories are not required for commands like `patch +send` and `issue new`. You can also pass repositories using the `--repo` +option or the `` argument for commands that accept them. The +supported formats for manual input are: + +- A [NIP-19] addressable event coordinate `naddr`. +- A [NIP-05] identifier and repository name, in the format + `/`. +- A set name that contains repository addresses. + +You do not need to specify relays for these commands if your `naddr` or `NIP-05` +identifier already includes relays; `n34` will automatically extract them. + +[NIP-19]: https://github.com/nostr-protocol/nips/blob/master/19.md +[NIP-05]: https://github.com/nostr-protocol/nips/blob/master/05.md diff --git a/docs/config/README.md b/docs/config/README.md new file mode 100644 index 0000000..23b4789 --- /dev/null +++ b/docs/config/README.md @@ -0,0 +1,7 @@ +# Manage Configuration + +Configuration allows you to set default values for various command parameters, +such as fallback relays, Proof of Work (PoW) difficulty, a default bunker URL, +and your Nostr private key (keyring). This avoids the need to enter your private key, +bunker URL, relays, or PoW difficulty for every command, making `n34` more +convenient to use. diff --git a/docs/config/bunker.md b/docs/config/bunker.md new file mode 100644 index 0000000..f65bc89 --- /dev/null +++ b/docs/config/bunker.md @@ -0,0 +1,27 @@ +# NIP-46 Bunker + +> `n34 config bunker` command + +**Usage:** +``` +Sets a URL of NIP-46 bunker server used for signing events + +Usage: n34 config bunker [BUNKER_URL] + +Arguments: + [BUNKER_URL] Nostr Connect URL for the bunker. Omit this to remove the current bunker URL +``` + +This command configures `n34` to use a remote signer ([NIP-46]), known as a +bunker, for all cryptographic operations. + +When `n34` communicates with the bunker, it uses a persistent, locally-generated +keypair. You should add this keypair's public key to your bunker's list of +authorized applications. This allows `n34` to operate securely without needing +direct access to your main private key. + +Once configured, actions such as fetching your public key or signing events are +delegated to the bunker. To remove the bunker configuration, run the command +again without providing a URL. + +[NIP-46]: https://github.com/nostr-protocol/nips/blob/master/46.md diff --git a/docs/config/keyring.md b/docs/config/keyring.md new file mode 100644 index 0000000..34ee883 --- /dev/null +++ b/docs/config/keyring.md @@ -0,0 +1,27 @@ +# Secret Key Keyring + +> `n34 config keyring` command + +**Usage:** +``` +Manages the secret key keyring, including enabling, disabling, or resetting it. + +Usage: n34 config keyring <--enable|--disable|--reset> + +Options: + --enable Enables the secret key keyring. You will be prompted for your key one last time to store it. + --disable Disables the secret key keyring. This removes the stored key and prevents new ones from being saved. + --reset Resets the keyring. This deletes the current key, allowing a new one to be stored on the next use. +``` + +To avoid entering your private key for every command, you can enable the keyring +to store it securely. First, run `n34 config keyring --enable`. The next time +you run an `n34` command that requires your private key, it will be saved +to your system's keyring. You will not need to enter it again for subsequent +commands. + +To replace the stored key with a new one, use the `--reset` flag. To stop using +the keyring and remove the stored key, use the `--disable` flag. + +`n34` uses your operating system's native secret management system. For example, +it uses `keyutils` on Linux and `Keychain` on macOS. diff --git a/docs/config/pow.md b/docs/config/pow.md new file mode 100644 index 0000000..fa0b279 --- /dev/null +++ b/docs/config/pow.md @@ -0,0 +1,20 @@ +# Default PoW Difficulty + +> `n34 config pow` + +**Usage:** +``` +Sets the default PoW difficulty (0 if not specified) + +Usage: n34 config pow + +Arguments: + The new default PoW difficulty +``` + +This command configures the default Proof of Work (PoW) difficulty for newly +created events. This setting is applied to most generated events, but it +intentionally skips patch events. Because patches can be numerous, calculating +PoW for each one would significantly slow down operations. + +If you want to disable the PoW just make it 0. diff --git a/docs/config/relays.md b/docs/config/relays.md new file mode 100644 index 0000000..d2c8685 --- /dev/null +++ b/docs/config/relays.md @@ -0,0 +1,21 @@ +# Fallback Relays + +> `n34 config relays` command + +**Usage:** +``` +Sets the default fallback relays if none provided. Use this relays for read and write + +Usage: n34 config relays [OPTIONS] [RELAYS]... + +Arguments: + [RELAYS]... List of relay URLs to append to fallback relays. If empty, removes all fallback relays + +Options: + --override Replace existing fallback relays instead of appending new ones +``` + +This command configures the default fallback relays, which `n34` uses to read +from and write to. To add relays, provide their URLs as arguments to append +them to the current list. Use the `--override` flag to replace the existing list +entirely. To clear all fallback relays, run the command without any arguments. diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..4e824b2 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,449 @@ + + + + + + + + + + + + + + + + n34 - CLI for NIP-34 and Nostr Code Collaboration + + + +
+
+
✨ Looking for feedback
+

n34

+

+ n34 is an open source command-line interface (CLI) tool for + sending and receiving Git issues, patches and comments over the + Nostr protocol. It supports creating, replying to, and managing + issues and patches, making Git collaboration decentralized and + censorship-resistant. +

+
+ Documentation + Git Repository +
+
+
+

Key Features

+
+
+

🔄Complete Git Workflow

+

Handle the full development lifecycle with patches, issues, replies, and status tracking, all through the decentralized Nostr protocol.

+
+
+

🔗NIP-34 Compliant

+

Fully implements the NIP-34 specification for Git repositories on Nostr, ensuring compatibility with the decentralized ecosystem.

+
+
+

🛠️Developer Friendly

+

Intuitive CLI interface designed for developers who want to integrate Git workflows with Nostr seamlessly.

+
+
+

🔐Self-Sovereign

+

No accounts, no passwords, no centralized servers. You control your identity and data through cryptographic keys.

+
+
+
+
+

Feature Roadmap

+

Current implementation status and upcoming features

+
+
+
    +
  • + + Repository announcements +
    • +
  • + + Repository state announcements +
    • +
  • + + Patches (Send, fetch and list) +
    • +
  • + + Issues (Send, view and list) +
    • +
  • + + Replies +
    • +
  • + + Issues and patches status +
    • +
  • + + Pull requests (nostr-protocol/nips#1966) +
    • +
+
+
+ +
+
+
+
+

Quick Start

+

Get started with n34 in seconds

+
cargo install n34
+

or

+
+ git clone https://git.4rs.nl/awiteb/n34.git && cd n34 && cargo build --release +
+

# The execautable will be in target/release/n34

+

+

Once installed, run n34 --help to see available commands.

+
+
+

Why Nostr?

+

+ Nostr is fundamentally different from traditional platforms because it's not an application or service, it's a decentralized protocol. This means any tool or app can integrate with it, enabling open, permissionless collaboration + without relying on centralized gatekeepers. Unlike proprietary systems, Nostr doesn't require emails, passwords, or accounts. You interact directly through relays, whether you self-host your own or use public ones, ensuring no + single point of failure or control. +

+

+ What makes Nostr uniquely resilient is its design, the protocol itself is just a set of rules, not a company or product that can disappear. Your Git issues, patches, and comments persist as long as relays choose to store them, + immune to the whims of corporate shutdowns or policy changes. Nostr is infrastructure in its purest form, an idea that outlives any temporary implementation. n34 taps into a future-proof foundation for decentralized collaboration. +

+
+

More about Nostr

+ +
+
+
+

Built with ❤️ for the decentralized future

+
+
+ + diff --git a/docs/issue/README.md b/docs/issue/README.md new file mode 100644 index 0000000..3e4ccae --- /dev/null +++ b/docs/issue/README.md @@ -0,0 +1,15 @@ +# Issue Management + +Using `n34`, you can manage Git issues stored in Nostr relays, adhering to +the [NIP-34] standard. In Nostr, events are immutable, meaning their IDs are +derived from the SHA-256 hash of their timestamp, content, author, and tags. +As a result, issues cannot be edited directly. However, with `n34`, you can +create new issues, view existing ones, or update their status—such as closing, +resolving, or reopening them. + +[NIP-34] introduces support for drafting issues, though this feature is not +currently implemented in `n34` due to the lack of a clear use case for drafting +issues. The inclusion of this functionality may stem from its shared use in both +issues and patches, suggesting it was primarily designed for patch management. + +[NIP-34]: https://github.com/nostr-protocol/nips/blob/master/34.md diff --git a/docs/issue/close.md b/docs/issue/close.md new file mode 100644 index 0000000..3d66379 --- /dev/null +++ b/docs/issue/close.md @@ -0,0 +1,19 @@ +# Closes an Open Issue + +> `n34 issue close` command + +**Usage:** +``` +Closes an open issue + +Usage: n34 issue close [OPTIONS] + +Arguments: + The open issue id to close it + +Options: + --repo Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel` +``` + +Issue a kind `1632` (Close status) for the specified issue. The issue have to +be open. diff --git a/docs/issue/list.md b/docs/issue/list.md new file mode 100644 index 0000000..ec5ccea --- /dev/null +++ b/docs/issue/list.md @@ -0,0 +1,19 @@ +# List Repositories Issues + +> `n34 issue list` command + +**Usage:** +``` +List the repositories issues + +Usage: n34 issue list [OPTIONS] [NADDR-NIP05-OR-SET]... + +Arguments: + [NADDR-NIP05-OR-SET]... Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel` + +Options: + --limit Maximum number of issues to list [default: 15] +``` + +List the repositories issues. By default `n34` will look for `nostr-address` +file and extract the repositories from it. diff --git a/docs/issue/new.md b/docs/issue/new.md new file mode 100644 index 0000000..59836d2 --- /dev/null +++ b/docs/issue/new.md @@ -0,0 +1,29 @@ +# Create an Issue + +> `n34 issue new` Command + +**Usage:** +``` +Create a new repository issue + +Usage: n34 issue new [OPTIONS] <--content |--editor> + +Options: + --repo Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel` + -c, --content Markdown content for the issue. Cannot be used together with the `--editor` flag + -e, --editor Opens the user's default editor to write issue content. The first line will be used as the issue subject + --subject The issue subject. Cannot be used together with the `--editor` flag + -l, --label