vde-layout 1.0.1 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +33 -7
- package/dist/index.mjs +566 -62
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -30,7 +30,7 @@ pnpm run ci
|
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
## Quick Start
|
|
33
|
-
1. Create a YAML file at `~/.config/vde/layout.yml` (
|
|
33
|
+
1. Create a YAML file at `~/.config/vde/layout/config.yml` (legacy `~/.config/vde/layout.yml` is also supported; see "Configuration Search Order").
|
|
34
34
|
2. Paste a preset definition:
|
|
35
35
|
```yaml
|
|
36
36
|
presets:
|
|
@@ -68,16 +68,23 @@ pnpm run ci
|
|
|
68
68
|
## CLI Commands
|
|
69
69
|
- `vde-layout [preset]` - Apply the named preset. When omitted, vde-layout uses the `default` preset; if none exists it lists available presets and exits.
|
|
70
70
|
- `vde-layout list` - Show available presets with descriptions.
|
|
71
|
+
- `vde-layout --select` - Open an interactive preset selector (auto mode; currently uses `fzf`).
|
|
72
|
+
- `vde-layout --select --select-ui fzf` - Force the selector backend (`auto` or `fzf`).
|
|
73
|
+
- `vde-layout --select --select-surface tmux-popup` - Render selector in a tmux popup (`fzf --tmux`).
|
|
74
|
+
- `vde-layout --select --select-tmux-popup-opts "80%,70%"` - Pass popup sizing/placement to `fzf --tmux=<opts>`.
|
|
75
|
+
- `vde-layout --select --fzf-arg "--cycle" --fzf-arg "--info=inline"` - Pass additional argument(s) to `fzf` (repeatable).
|
|
71
76
|
- `vde-layout dev --dry-run` - Display the tmux steps without executing them.
|
|
72
77
|
- `vde-layout dev --verbose` - Print informational logs, including resolved presets and plan details.
|
|
73
78
|
- `vde-layout dev --backend wezterm` - Use the WezTerm backend (defaults to `tmux` when omitted).
|
|
74
79
|
- `vde-layout dev --current-window` - Reuse the current tmux window (or active WezTerm tab) after confirming that other panes can be closed.
|
|
75
80
|
- `vde-layout dev --new-window` - Force creation of a new tmux window or WezTerm tab even when presets or defaults request reuse.
|
|
76
|
-
- `vde-layout --config /path/to/
|
|
81
|
+
- `vde-layout --config /path/to/config.yml` - Load presets from a specific file.
|
|
77
82
|
- `vde-layout --help` - Show usage.
|
|
78
83
|
- `vde-layout --version` / `vde-layout -v` - Print package version.
|
|
79
84
|
|
|
80
85
|
> **Note:** Applying a preset (without `--dry-run`) must be done inside an active tmux session when using the tmux backend. For the WezTerm backend, ensure a WezTerm window is running and focused so the CLI can discover it.
|
|
86
|
+
>
|
|
87
|
+
> **Selector UI note:** `--select` requires an interactive terminal and `fzf` on `$PATH`. `--select-surface tmux-popup` requires running inside tmux (`fzf --tmux`, tmux 3.3+ recommended).
|
|
81
88
|
|
|
82
89
|
## Terminal Backends
|
|
83
90
|
vde-layout resolves backends in the following order: CLI flag (`--backend`), preset configuration, then defaults to `tmux`.
|
|
@@ -88,12 +95,16 @@ vde-layout resolves backends in the following order: CLI flag (`--backend`), pre
|
|
|
88
95
|
- `--new-window` spawns a new tab in the active window when one is available, otherwise creates a fresh window.
|
|
89
96
|
|
|
90
97
|
## Configuration Search Order
|
|
91
|
-
When no `--config` flag is provided, vde-layout
|
|
92
|
-
1.
|
|
93
|
-
2. `$
|
|
94
|
-
3.
|
|
98
|
+
When no `--config` flag is provided, vde-layout checks candidate files in this order for `findConfigFile()`:
|
|
99
|
+
1. Project scope discovered by walking up from the current directory; for each directory, vde-layout checks `.vde/layout/config.yml` first, then `.vde/layout.yml`.
|
|
100
|
+
2. `$VDE_CONFIG_PATH/layout.yml` (if `VDE_CONFIG_PATH` is set).
|
|
101
|
+
3. `$XDG_CONFIG_HOME/vde/layout/config.yml` (or `~/.config/vde/layout/config.yml` when `XDG_CONFIG_HOME` is unset).
|
|
102
|
+
4. `$XDG_CONFIG_HOME/vde/layout.yml` fallback (or `~/.config/vde/layout.yml`).
|
|
95
103
|
|
|
96
|
-
|
|
104
|
+
For `loadConfig()`, vde-layout merges shared scopes first and project scope last:
|
|
105
|
+
1. `$VDE_CONFIG_PATH/layout.yml`
|
|
106
|
+
2. XDG scope (`.../vde/layout/config.yml` or fallback `.../vde/layout.yml`; first existing file only)
|
|
107
|
+
3. Project scope (`<project-root>/.vde/layout/config.yml` or fallback `<project-root>/.vde/layout.yml`, discovered by walking up from the current directory)
|
|
97
108
|
|
|
98
109
|
## Preset Structure
|
|
99
110
|
Each preset is an object under the `presets` key:
|
|
@@ -109,6 +120,21 @@ presets:
|
|
|
109
120
|
command: "htop" # optional; used when layout is omitted
|
|
110
121
|
```
|
|
111
122
|
|
|
123
|
+
### Defaults Structure
|
|
124
|
+
Global/project defaults can be defined under `defaults`:
|
|
125
|
+
```yaml
|
|
126
|
+
defaults:
|
|
127
|
+
windowMode: new-window
|
|
128
|
+
selector:
|
|
129
|
+
ui: auto # auto | fzf
|
|
130
|
+
surface: auto # auto | inline | tmux-popup
|
|
131
|
+
tmuxPopupOpts: "80%,70%" # passed to fzf as --tmux=<value>
|
|
132
|
+
fzf:
|
|
133
|
+
extraArgs: # additional arguments passed to fzf
|
|
134
|
+
- --cycle
|
|
135
|
+
- --info=inline
|
|
136
|
+
```
|
|
137
|
+
|
|
112
138
|
### Layout Structure
|
|
113
139
|
```yaml
|
|
114
140
|
layout:
|