qrlkit 0.10.3 → 0.12.0

package/README.md

@@ -113,9 +113,9 @@ cargo install --path .
 ## Version 1 Roadmap
 
 **Version 1 happens January 2027. Until then expect everything to break. 
-Current version is 0.5.5 but any minor version can ship with a breaking change until v1.**
+Current version is 0.10.3 but any minor version can ship with a breaking change until v1.**
 
-### Version 1
+### Version 1.0.0 goals 
 
 #### `qrlkit` ####
 
@@ -175,7 +175,14 @@ Current version is 0.5.5 but any minor version can ship with a breaking change u
 | `qrlkit set-dirhook <command>` | Choose the directory hook (`--clear` restores changing directory) |
 | `qrlkit init` | Choose browser, shell, filehook, and dirhook interactively |
 | `qrlkit init <shell>` | Print the directory wrapper for manual setup |
-| `qrlkit nuke` | Reset imports, renames, browser selection, and hooks |
+| `qrlkit nuke` | Reset imports, renames, browser selection, hooks, and theme settings |
+| `qrlkit themes` | List themes with previews |
+| `qrlkit themes current` | Show the global theme and tool policy |
+| `qrlkit themes add <file>` | Import a theme without activating it |
+| `qrlkit themes set [name]` | Set the global theme; omit name for live previews |
+| `qrlkit themes tools <on/off>` | Enable or disable tool themes |
+| `qrlkit themes tools deny <tool>` | Ignore a tool's theme |
+| `qrlkit themes tools reset <tool>` | Remove a tool's theme exclusion |
 | `qrlkit --help` | Show help |
 
 `nuke` keeps your original config files and installed shell integration.
@@ -188,8 +195,10 @@ State is stored in `$XDG_STATE_HOME/qrlkit/state.yaml` on Linux, falling back to
 
 Each example replaces the previous one.
 
-Resource arguments match every placeholder name.
-CLI values follow argument declaration order.
+References use their full path, like `{shared.repos}`.
+Strings supply fixed values. Lists offer choices when no value is supplied.
+CLI values follow first-reference order, including lookup inputs.
+Use `args` to declare argument order. Repeated references reuse the same selection.
 
 ### URLs
 
@@ -207,42 +216,42 @@ Choose the repository with an argument.
 open = "https://github.com/qrlkit/{repo}"
 ```
 
-Reuse an organization through a constant.
+Reuse an organization.
 
 ```toml
-[constants]
+[shared]
+hidden = true
 org = "qrlkit"
 
 [repos]
-open = "https://github.com/{constants.org}/{repo}"
+open = "https://github.com/{shared.org}/{repo}"
 ```
 
 Add hints and override the browser.
 
 ```toml
-[constants]
+[shared]
+hidden = true
 org = "qrlkit"
 
 [repos]
 browser = "firefox"
 # hint: Browse the source code
-open = "https://github.com/{constants.org}/{repo}"
+open = "https://github.com/{shared.org}/{repo}"
 ```
 
-Offer repository choices from a constant.
+Offer repository choices.
 
 ```toml
-[constants]
+[shared]
+hidden = true
 org = "qrlkit"
 repos = ["qrlkit-rs", "qrlkit-web"]
 
 [repos.open]
-url = "https://github.com/{constants.org}/{repo}"
+url = "https://github.com/{shared.org}/{shared.repos}"
 hint = "Browse the source code"
 browser = "firefox"
-args = [
-  { name = "repo", enum = { ref = "constants.repos" } },
-]
 ```
 
 ```sh
@@ -274,37 +283,38 @@ readme = "~/dev/{repo}/README.md"
 Reuse your development directory across paths.
 
 ```toml
-[constants]
+[shared]
+hidden = true
 root = "~/dev"
 
 [files]
-readme = "{constants.root}/{repo}/README.md"
+readme = "{shared.root}/{repo}/README.md"
 ```
 
 Add hints and open your editor.
 
 ```toml
-[constants]
+[shared]
+hidden = true
 root = "~/dev"
 
 [files]
 filehook = "nvim $file"
-readme = "{constants.root}/{repo}/README.md" # hint: Edit the project README
+readme = "{shared.root}/{repo}/README.md" # hint: Edit the project README
 ```
 
 Offer project choices before opening files.
 
 ```toml
-[constants]
+[shared]
+hidden = true
 root = "~/dev"
+repos = ["qrlkit-rs", "qrlkit-web"]
 
 [files.readme]
-url = "{constants.root}/{repo}/README.md"
+url = "{shared.root}/{shared.repos}/README.md"
 hint = "Edit the project README"
 filehook = "nvim $file"
-args = [
-  { name = "repo", enum = ["qrlkit-rs", "qrlkit-web"] },
-]
 ```
 
 ```sh
@@ -333,38 +343,39 @@ project = "~/dev/{repo}"
 Reuse your development directory across projects.
 
 ```toml
-[constants]
+[shared]
+hidden = true
 root = "~/dev"
 
 [dirs]
-project = "{constants.root}/{repo}"
+project = "{shared.root}/{repo}"
 ```
 
 Add hints and list directory contents.
 
 ```toml
-[constants]
+[shared]
+hidden = true
 root = "~/dev"
 
 [dirs]
 dirhook = "cd $dir && tree -L 1"
 # hint: Enter and inspect the project
-project = "{constants.root}/{repo}"
+project = "{shared.root}/{repo}"
 ```
 
 Offer project choices before changing directories.
 
 ```toml
-[constants]
+[shared]
+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
@@ -391,40 +402,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"]
 
@@ -432,7 +446,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"
@@ -440,7 +454,7 @@ printf 'Have a lovely day!\n'
 '''
 
 [greet.env]
-NAME = "{constants.name}"
+NAME = "{shared.name}"
 ```
 
 ```sh
@@ -449,31 +463,236 @@ qrlkit greet Hey
 
 Supported shells: `bash`, `sh`, and `zsh`.
 
-### Shared constants
+Use a script's output in another resource.
+
+```toml
+[system]
+hidden = true
+
+[system.hostname]
+run = "hostname"
+
+[logs]
+url = "https://logs.example.com/search?host={system.hostname}"
+```
+
+Referenced scripts run only when needed. Their stdout is reused within the command,
+with trailing newlines removed. A failed script stops the command.
+Script bodies stay literal; use `args` and `env` to pass values.
+
+### 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}"
+```
+
+`constants.toml` is no longer loaded automatically. Register shared values explicitly
+and replace `{global.name}` with their full path. `constants` is now an ordinary group.
+
+### Composition
+
+Reference another resource's target without opening it.
+
+```toml
+[shared]
+hidden = true
+repos = ["qrlkit-rs", "qrlkit-web"]
+
+[repos.open]
+url = "https://github.com/qrlkit/{shared.repos}"
+
+[repos.prs]
+url = "{repos.open}/pulls"
+```
+
+```sh
+repos prs qrlkit-web  # Opens the repository's pull requests
+repos prs            # Choose the repository
+```
+
+Missing references and circular dependencies are errors.
+
+### Lookups
+
+Choose a URL part from a mapping. Use one selector for a flat mapping,
+or multiple selectors to walk nested mappings.
+
+```toml
+[projects]
+hidden = true
+repos = ["qrlkit-rs", "qrlkit-web"]
+
+[shared]
+hidden = true
+environments = ["sim", "live"]
+
+[logs]
+url = "https://{logs.subdomains[projects.repos, shared.environments]}.logs.example.com"
+
+[logs.subdomains]
+hidden = true
+
+[logs.subdomains.qrlkit-rs]
+sim = "rust-sandbox"
+live = "rust-production"
+
+[logs.subdomains.qrlkit-web]
+sim = "web-sandbox"
+live = "web-production"
+```
+
+Put `url` directly on a group to call it without a subcommand.
+
+```sh
+logs qrlkit-rs live  # Opens https://rust-production.logs.example.com
+logs qrlkit-rs       # Choose the environment
+logs                 # Choose the repository and environment
+```
+
+Missing lookup keys are errors. Child commands take precedence over arguments;
+use `--` before a value that matches a child command's name.
+
+### 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.
+
+Available themes:
+`terminal` (default), `catppuccin-latte`, `catppuccin-mocha`, `dracula`,
+`gruvbox-dark`, `gruvbox-light`, `nord`, and `tokyo-night`.
+
+Preview the themes and choose a global default.
+
+```sh
+qrlkit themes              # List themes with previews
+qrlkit themes set          # Preview as you navigate; Enter saves, Esc cancels
+qrlkit themes set dracula  # Choose directly
+qrlkit themes current      # Show your theme and tool policy
 ```
 
+Give a tool its own theme in the config.
+
+```toml
+[gh]
+theme = "dracula"
+home = "https://github.com"
+```
+
+Or choose the colors, box and selection marker yourself.
+
+```toml
+[gh]
+home = "https://github.com"
+
+[gh.theme]
+background = "#1e1e2e"
+text = "#cdd6f4"
+selected = "#ffffff"
+selected_background = "#45475a"
+hint = "#a6adc8"
+title = "#cba6f7"
+border = "rounded"         # none, plain, rounded, or double
+border_color = "#9399b2"
+marker = "--x"
+selection_width = "row"     # Or content: highlight only the marker, key and hint
+```
+
+Nested keys keep their parent's theme unless they define their own.
+A new theme replaces the whole thing. Missing values use terminal colors,
+no border, a `>` marker and full-row selection. Themes are never mixed.
+Use `"default"` for a color to restore your terminal's color.
+
+Save your own global theme in a separate file with a name inside `[theme]`.
+
+```toml
+# personal-theme.toml
+[theme]
+name = "personal"
+background = "#1e1e2e"
+text = "#cdd6f4"
+selected = "#cba6f7"
+selected_background = "#45475a"
+border = "rounded"
+```
+
+```sh
+qrlkit themes add personal-theme.toml
+qrlkit themes set personal
+```
+
+Importing saves a copy and adds it to the list.
+
+Tool themes are on by default. Turn them off to use your global theme everywhere,
+or exclude a single tool and all its nested keys.
+
+```sh
+qrlkit themes tools off      # Use your global theme everywhere
+qrlkit themes tools on       # Use tool themes where defined
+qrlkit themes tools deny gh  # Use your global theme for gh
+qrlkit themes tools reset gh # Remove gh's exclusion
+```
+
+Tools without a theme use your global default. Exclusions survive off/on toggles.
+`qrlkit nuke` resets the theme to `terminal`, enables tool themes and removes
+exclusions and imported themes.
+
 ## Contributing
 
 Contributions are welcome! 

package/package.json

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