qrlkit 0.11.0 → 0.12.1

package/README.md

@@ -193,63 +193,27 @@ State is stored in `$XDG_STATE_HOME/qrlkit/state.yaml` on Linux, falling back to
 
 ## Config syntax
 
-Each example replaces the previous one.
-
-Resource arguments match every placeholder name.
-CLI values follow argument declaration order.
-
 ### URLs
 
 Open URLs in your default browser.
 
 ```toml
 [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}"
+rs = "https://github.com/qrlkit/qrlkit-rs"
 ```
 
-Offer repository choices from a constant.
+Or go advanced with reuseable constants and hints.
 
 ```toml
-[constants]
+[const]
+hidden = true
 org = "qrlkit"
 repos = ["qrlkit-rs", "qrlkit-web"]
 
 [repos.open]
-url = "https://github.com/{constants.org}/{repo}"
+url = "https://github.com/{const.org}/{const.repos}"
 hint = "Browse the source code"
 browser = "firefox"
-args = [
-  { name = "repo", enum = { ref = "constants.repos" } },
-]
 ```
 
 ```sh
@@ -271,47 +235,18 @@ Print file paths without configured hooks.
 readme = "~/dev/qrlkit-rs/README.md"
 ```
 
-Choose the project with an argument.
+Or beef it up with reuseable constants, hints and a custom filehook: 
 
 ```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"
-readme = "{constants.root}/{repo}/README.md" # hint: Edit the project README
-```
-
-Offer project choices before opening files.
-
-```toml
-[constants]
+[const]
+hidden = true
 root = "~/dev"
+repos = ["qrlkit-rs", "qrlkit-web"]
 
 [files.readme]
-url = "{constants.root}/{repo}/README.md"
+url = "{const.root}/{const.repos}/README.md"
 hint = "Edit the project README"
 filehook = "nvim $file"
-args = [
-  { name = "repo", enum = ["qrlkit-rs", "qrlkit-web"] },
-]
 ```
 
 ```sh
@@ -319,59 +254,27 @@ qrlkit files readme qrlkit-rs  # Open directly
 qrlkit files readme            # Choose interactively
 ```
 
-Set global defaults with `qrlkit set-filehook`.
-
 ### Dirs
 
-Change directories through the shell integration.
+By default you can `cd` into a dir: 
 
 ```toml
 [dirs]
 project = "~/dev/qrlkit-rs"
 ```
 
-Choose the project with an argument.
+Or mod it similarly to files and urls with consts, dirhooks and hints:  
 
 ```toml
-[dirs]
-project = "~/dev/{repo}"
-```
-
-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}"
-```
-
-Offer project choices before changing directories.
-
-```toml
-[constants]
+[const]
+hidden = true
 root = "~/dev"
+repos = ["qrlkit-rs", "qrlkit-web"]
 
 [dirs.project]
-url = "{constants.root}/{repo}"
+url = "{shared.root}/{shared.repos}"
 hint = "Enter and inspect the project"
 dirhook = "cd $dir && tree -L 1"
-args = [
-  { name = "repo", enum = ["qrlkit-rs", "qrlkit-web"] },
-]
 ```
 
 ```sh
@@ -379,8 +282,6 @@ qrlkit dirs project qrlkit-rs  # Open directly
 qrlkit dirs project            # Choose interactively
 ```
 
-Set global defaults with `qrlkit set-dirhook`.
-
 ### Scripts
 
 Run Bash from the config's directory.
@@ -398,40 +299,43 @@ args = [{ name = "name" }]
 run = 'printf "Hello, %s!\n" "$1"'
 ```
 
-Supply constants through `env` without prompting.
+Supply fixed values through `env` without prompting.
 
 ```toml
-[constants]
+[shared]
+hidden = true
 name = "World"
 
 [greet]
 run = 'printf "Hello, %s!\n" "$NAME"'
 
 [greet.env]
-NAME = "{constants.name}"
+NAME = "{shared.name}"
 ```
 
-Combine constant values with argument choices.
+Combine shared values with argument choices.
 
 ```toml
-[constants]
+[shared]
+hidden = true
 name = "World"
 greetings = ["Hello", "Hi", "Hey"]
 
 [greet]
 args = [
-  { name = "greeting", enum = { ref = "constants.greetings" } },
+  { name = "greeting", enum = { ref = "shared.greetings" } },
 ]
 run = 'printf "%s, %s!\n" "$1" "$NAME"'
 
 [greet.env]
-NAME = "{constants.name}"
+NAME = "{shared.name}"
 ```
 
 Add hints and choose your shell.
 
 ```toml
-[constants]
+[shared]
+hidden = true
 name = "World"
 greetings = ["Hello", "Hi", "Hey"]
 
@@ -439,7 +343,7 @@ greetings = ["Hello", "Hi", "Hey"]
 hint = "Say hello with some personality"
 shell = "zsh"
 args = [
-  { name = "greeting", enum = { ref = "constants.greetings" } },
+  { name = "greeting", enum = { ref = "shared.greetings" } },
 ]
 run = '''
 printf '%s, %s!\n' "$1" "$NAME"
@@ -447,7 +351,7 @@ printf 'Have a lovely day!\n'
 '''
 
 [greet.env]
-NAME = "{constants.name}"
+NAME = "{shared.name}"
 ```
 
 ```sh
@@ -456,31 +360,109 @@ qrlkit greet Hey
 
 Supported shells: `bash`, `sh`, and `zsh`.
 
-### Shared constants
+### Shared values
 
-Place `constants.toml` beside your state file.
+Put shared values in any config and register it with `qrlkit add`.
 
 ```toml
-# constants.toml
-[constants]
+# shared.toml
+[shared]
+hidden = true
 root = "~/dev"
 name = "World"
 ```
 
-Reference shared constants with `{global.name}` syntax.
+```sh
+qrlkit add shared.toml
+```
+
+Reference them from other registered configs.
 
 ```toml
 # QRLs.toml
 [dirs]
-project = "{global.root}/{repo}"
+project = "{shared.root}/{repo}"
 
 [greet]
 run = 'printf "Hello, %s!\n" "$NAME"'
 
 [greet.env]
-NAME = "{global.name}"
+NAME = "{shared.name}"
+```
+
+### Composition
+
+Reference another resource's target without opening it.
+
+```toml
+# Reference another QRL's value or URL
+url = "{project.home}/issues"
+```
+
+```toml
+# Use a script's output
+[branch]
+run = "git branch --show-current"
+
+[compare]
+url = "{project.home}/compare/main...{branch}"
+```
+
+```toml
+# Look up a value using one selector
+[project]
+environment = ["staging", "production"]
+
+[open]
+url = "https://{hosts[project.environment]}.example.com"
 ```
 
+```toml
+# Walk a nested mapping using multiple selectors
+[project]
+name = ["api", "web"]
+environment = ["staging", "production"]
+
+[open]
+url = "https://{hosts[project.name, project.environment]}.example.com"
+```
+
+Missing references and circular dependencies are errors.
+
+### Hints and hidden groups
+
+Hide a group from pickers with `hidden = true`. Its values can still be referenced
+or called directly. Add hints to groups, tools, lists, and individual choices.
+
+```toml
+[projects]
+hidden = true
+
+[projects.repos]
+hint = "Choose a qrlkit project"
+values = [
+  { value = "qrlkit-rs", hint = "Rust CLI" },
+  { value = "qrlkit-web", hint = "Documentation website" },
+]
+
+[repos]
+hint = "GitHub resources"
+
+[repos.open]
+hint = "Browse the repository"
+url = "https://github.com/qrlkit/{projects.repos}"
+```
+
+```sh
+repos open       # Choose a repository with hints
+projects repos   # Choose and print a value from the hidden group
+```
+
+Use `values = ["qrlkit-rs", "qrlkit-web"]` when only the list needs a hint.
+Each tool keeps its own hint when composing resources.
+
+See [examples/composition.toml](examples/composition.toml) for a complete config.
+
 ## Themes
 
 Make the picker fit your terminal.

package/package.json

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