init

README.md

@@ -0,0 +1,80 @@
+# nix-shorturl-plugin
+
+A Nix plugin that lets you define custom short URL schemes for flake references.
+
+For example, `myorg:mylib` can expand to `github:my-organization/mylib`.
+
+## How it works
+
+The plugin registers a custom `InputScheme` that intercepts URL resolution. When Nix encounters a URL like `myorg:mylib`, the plugin:
+
+1. Matches `myorg` against your configured schemes
+2. Expands the template (e.g., `github:my-organization/{path}` becomes `github:my-organization/mylib`)
+3. Delegates to the built-in scheme (e.g., the GitHub fetcher)
+
+Lock files store the **real** resolved type (e.g., `type = "github"`), not `type = "shorturl"`. This means lock files work on machines that don't have the plugin installed.
+
+## Installation
+
+```bash
+nix build github:yourusername/nix-shorturl-plugin
+```
+
+Then add to your Nix configuration (`~/.config/nix/nix.conf`):
+
+```
+plugin-files = /path/to/result/lib/nix/plugins/libnix-shorturl-plugin.so
+```
+
+Or use it ad-hoc:
+
+```bash
+nix --option plugin-files ./result/lib/nix/plugins/libnix-shorturl-plugin.so flake metadata myorg:mylib
+```
+
+## Configuration
+
+Create `~/.config/nix/shorturl.json` (or set `NIX_SHORTURL_CONFIG`):
+
+```json
+{
+  "schemes": {
+    "myorg": {
+      "template": "github:my-organization/{path}"
+    },
+    "internal": {
+      "template": "git+ssh://git.internal.corp/{path}"
+    },
+    "gl": {
+      "template": "gitlab:mycompany/{path}"
+    }
+  }
+}
+```
+
+### Template syntax
+
+- `{path}` is replaced with everything after the colon in the short URL
+- Query parameters and fragments from the original URL are passed through
+
+### Examples
+
+| Short URL | Expanded URL |
+|---|---|
+| `myorg:mylib` | `github:my-organization/mylib` |
+| `myorg:libs/mylib?ref=develop` | `github:my-organization/libs/mylib?ref=develop` |
+| `gl:project` | `gitlab:mycompany/project` |
+
+## Config path resolution
+
+1. `NIX_SHORTURL_CONFIG` environment variable
+2. `$XDG_CONFIG_HOME/nix/shorturl.json`
+3. `~/.config/nix/shorturl.json`
+
+## Development
+
+```bash
+nix develop
+meson setup build
+ninja -C build
+```