qrlkit 0.9.3 → 0.10.1

package/README.md

@@ -186,105 +186,293 @@ State is stored in `$XDG_STATE_HOME/qrlkit/state.yaml` on Linux, falling back to
 
 ## Config syntax
 
-**URLs**
+Each example replaces the previous one.
 
-Urls open in the default browser set in `qrlkit init` or `qrlkit set-browser`. 
-Reserved key `browser` overrides it with options:
+Resource arguments match every placeholder name.
+CLI values follow argument declaration order.
 
-- `chrome` 
-- `firefox`
-- `safari`
-- `edge`
-- `brave`
-- `chromium`
-- `arc`
-- `vivaldi`
-- `opera`
+### URLs
 
-Executable paths are also supported. 
-Use `{}` to forward arguments to paths. 
+Open URLs in your default browser.
 
 ```toml
-[docs]
+[repos]
+open = "https://github.com/qrlkit/qrlkit-rs"
+```
+
+Choose the repository with an argument.
+
+```toml
+[repos]
+open = "https://github.com/qrlkit/{repo}"
+```
+
+Reuse an organization through a constant.
+
+```toml
+[constants]
+org = "qrlkit"
+
+[repos]
+open = "https://github.com/{constants.org}/{repo}"
+```
+
+Add hints and override the browser.
+
+```toml
+[constants]
+org = "qrlkit"
+
+[repos]
+browser = "firefox"
+# hint: Browse the source code
+open = "https://github.com/{constants.org}/{repo}"
+```
+
+Offer repository choices from a constant.
+
+```toml
+[constants]
+org = "qrlkit"
+repos = ["qrlkit-rs", "qrlkit-web"]
+
+[repos.open]
+url = "https://github.com/{constants.org}/{repo}"
+hint = "Browse the source code"
 browser = "firefox"
-fav = "https://some-docs-you-prefer-in-ff/{area}.com"
+args = [
+  { name = "repo", enum = { ref = "constants.repos" } },
+]
+```
+
+```sh
+qrlkit repos open qrlkit-rs  # Open directly
+qrlkit repos open            # Choose interactively
 ```
 
-**files**
+Supported browsers:
+`chrome`, `firefox`, `safari`, `edge`, `brave`, `chromium`, `arc`, `vivaldi`, `opera`.
 
-Files use the default action set in `qrlkit init` or `qrlkit set-filehook`.
-If neither is used they just otherwise print the file path.
-Reserved key `filehook` overrides global behavior with a command using `$file` for the selected path.
-Use `{}` in paths to forward arguments. 
+Custom browser executable paths also work.
+
+### Files
+
+Print file paths without configured hooks.
 
 ```toml
-[dotfiles]
+[files]
+readme = "~/dev/qrlkit-rs/README.md"
+```
+
+Choose the project with an argument.
+
+```toml
+[files]
+readme = "~/dev/{repo}/README.md"
+```
+
+Reuse your development directory across paths.
+
+```toml
+[constants]
+root = "~/dev"
+
+[files]
+readme = "{constants.root}/{repo}/README.md"
+```
+
+Add hints and open your editor.
+
+```toml
+[constants]
+root = "~/dev"
+
+[files]
 filehook = "nvim $file"
-edit = "~/.confg/{tool}/{file}"
+readme = "{constants.root}/{repo}/README.md" # hint: Edit the project README
 ```
 
-**dirs**
+Offer project choices before opening files.
+
+```toml
+[constants]
+root = "~/dev"
+
+[files.readme]
+url = "{constants.root}/{repo}/README.md"
+hint = "Edit the project README"
+filehook = "nvim $file"
+args = [
+  { name = "repo", enum = ["qrlkit-rs", "qrlkit-web"] },
+]
+```
+
+```sh
+qrlkit files readme qrlkit-rs  # Open directly
+qrlkit files readme            # Choose interactively
+```
+
+Set global defaults with `qrlkit set-filehook`.
+
+### Dirs
 
-Dirs use the default action set in `qrlkit init` or `qrlkit set-dirhook`.
-If neither is used they otherwise just `cd` into directory via shell integration.
-Reserved key `dirhook` overrides global behavior with a command using `$dir` for the selected path.
+Change directories through the shell integration.
+
+```toml
+[dirs]
+project = "~/dev/qrlkit-rs"
+```
+
+Choose the project with an argument.
 
 ```toml
 [dirs]
-dirhook = "cd $dir && tree -L 1"
 project = "~/dev/{repo}"
 ```
 
-**constants**
+Reuse your development directory across projects.
+
+```toml
+[constants]
+root = "~/dev"
+
+[dirs]
+project = "{constants.root}/{repo}"
+```
+
+Add hints and list directory contents.
+
+```toml
+[constants]
+root = "~/dev"
+
+[dirs]
+dirhook = "cd $dir && tree -L 1"
+# hint: Enter and inspect the project
+project = "{constants.root}/{repo}"
+```
 
-Define reusable strings or lists in `[constants]`. Use `{constants.name}` in paths and URLs. For shared values, put `[constants]` in `constants.toml` beside the state file and use `{global.name}`.
+Offer project choices before changing directories.
 
 ```toml
 [constants]
 root = "~/dev"
-namespaces = ["dev", "staging", "prod"]
 
-[projects]
-api = "{constants.root}/api"
+[dirs.project]
+url = "{constants.root}/{repo}"
+hint = "Enter and inspect the project"
+dirhook = "cd $dir && tree -L 1"
+args = [
+  { name = "repo", enum = ["qrlkit-rs", "qrlkit-web"] },
+]
+```
+
+```sh
+qrlkit dirs project qrlkit-rs  # Open directly
+qrlkit dirs project            # Choose interactively
 ```
 
-**scripts**
+Set global defaults with `qrlkit set-dirhook`.
+
+### Scripts
 
-Scripts run in Bash by default from the config's directory.
-Reserved key `shell` overrides it with options `bash`, `sh`, and `zsh`.
-Use `$` notation to pass arguments. Use args to prompt users for inputs.
+Run Bash from the config's directory.
 
 ```toml
-[kube.logs]
+[greet]
+run = 'printf "Hello, World!\n"'
+```
+
+Prompt for missing arguments with `args`.
+
+```toml
+[greet]
+args = [{ name = "name" }]
+run = 'printf "Hello, %s!\n" "$1"'
+```
+
+Supply constants through `env` without prompting.
+
+```toml
+[constants]
+name = "World"
+
+[greet]
+run = 'printf "Hello, %s!\n" "$NAME"'
+
+[greet.env]
+NAME = "{constants.name}"
+```
+
+Combine constant values with argument choices.
+
+```toml
+[constants]
+name = "World"
+greetings = ["Hello", "Hi", "Hey"]
+
+[greet]
 args = [
-  { name = "namespace", enum = { ref = "constants.namespaces" } },
-  { name = "pod" },
+  { name = "greeting", enum = { ref = "constants.greetings" } },
+]
+run = 'printf "%s, %s!\n" "$1" "$NAME"'
+
+[greet.env]
+NAME = "{constants.name}"
+```
+
+Add hints and choose your shell.
+
+```toml
+[constants]
+name = "World"
+greetings = ["Hello", "Hi", "Hey"]
+
+[greet]
+hint = "Say hello with some personality"
+shell = "zsh"
+args = [
+  { name = "greeting", enum = { ref = "constants.greetings" } },
 ]
 run = '''
-kubectl logs --namespace "$1" "$2" --follow
+printf '%s, %s!\n' "$1" "$NAME"
+printf 'Have a lovely day!\n'
 '''
-shell = "zsh"
+
+[greet.env]
+NAME = "{constants.name}"
 ```
 
-**hints**
+```sh
+qrlkit greet Hey
+```
 
-Comments with `hint: ` in them will be included in the terminal.
+Supported shells: `bash`, `sh`, and `zsh`.
 
-```toml
-[launch]
-# hint: Find your next mission
-issues = "https://github.com/ratatui/ratatui/issues"
+### Shared constants
 
-repo = "https://github.com/ratatui/ratatui" # hint: Browse the source code
+Place `constants.toml` beside your state file.
+
+```toml
+# constants.toml
+[constants]
+root = "~/dev"
+name = "World"
 ```
 
-Run `qrlkit launch` after importing the config:
+Reference shared constants with `{global.name}` syntax.
 
-```text
-> issues        Find your next mission
-  repo          Browse the source code
-```
+```toml
+# QRLs.toml
+[dirs]
+project = "{global.root}/{repo}"
 
+[greet]
+run = 'printf "Hello, %s!\n" "$NAME"'
+
+[greet.env]
+NAME = "{global.name}"
+```
 
 ## Contributing
 

package/package.json

@@ -9,10 +9,10 @@
     "README.md"
   ],
   "optionalDependencies": {
-    "qrlkit-darwin-arm64": "0.9.3",
-    "qrlkit-darwin-x64": "0.9.3",
-    "qrlkit-linux-arm64": "0.9.3",
-    "qrlkit-linux-x64": "0.9.3"
+    "qrlkit-darwin-arm64": "0.10.1",
+    "qrlkit-darwin-x64": "0.10.1",
+    "qrlkit-linux-arm64": "0.10.1",
+    "qrlkit-linux-x64": "0.10.1"
   },
   "os": [
     "linux",
@@ -34,5 +34,5 @@
   "bugs": {
     "url": "https://github.com/qrlkit/qrlkit-rs/issues"
   },
-  "version": "0.9.3"
+  "version": "0.10.1"
 }