scriptvault 0.2.1b0__tar.gz → 0.4.0__tar.gz

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.
Files changed (33) hide show
  1. {scriptvault-0.2.1b0/src/scriptvault.egg-info → scriptvault-0.4.0}/PKG-INFO +113 -5
  2. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/README.md +111 -4
  3. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/pyproject.toml +3 -3
  4. scriptvault-0.4.0/src/scriptvault/__init__.py +8 -0
  5. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/src/scriptvault/cli.py +316 -220
  6. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/src/scriptvault/run.py +195 -48
  7. scriptvault-0.4.0/src/scriptvault/templates.py +362 -0
  8. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/src/scriptvault/term.py +1 -1
  9. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/src/scriptvault/vault.py +176 -142
  10. {scriptvault-0.2.1b0 → scriptvault-0.4.0/src/scriptvault.egg-info}/PKG-INFO +113 -5
  11. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/src/scriptvault.egg-info/SOURCES.txt +2 -0
  12. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/src/scriptvault.egg-info/requires.txt +1 -0
  13. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/tests/test_add.py +74 -0
  14. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/tests/test_completion.py +20 -0
  15. scriptvault-0.4.0/tests/test_guide.py +76 -0
  16. scriptvault-0.4.0/tests/test_hooks.py +181 -0
  17. scriptvault-0.4.0/tests/test_init.py +238 -0
  18. scriptvault-0.4.0/tests/test_list.py +386 -0
  19. scriptvault-0.4.0/tests/test_run.py +816 -0
  20. scriptvault-0.2.1b0/src/scriptvault/__init__.py +0 -8
  21. scriptvault-0.2.1b0/src/scriptvault/templates.py +0 -93
  22. scriptvault-0.2.1b0/tests/test_init.py +0 -95
  23. scriptvault-0.2.1b0/tests/test_list.py +0 -95
  24. scriptvault-0.2.1b0/tests/test_run.py +0 -462
  25. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/LICENSE +0 -0
  26. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/setup.cfg +0 -0
  27. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/src/scriptvault/__main__.py +0 -0
  28. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/src/scriptvault/envfile.py +0 -0
  29. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/src/scriptvault.egg-info/dependency_links.txt +0 -0
  30. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/src/scriptvault.egg-info/entry_points.txt +0 -0
  31. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/src/scriptvault.egg-info/top_level.txt +0 -0
  32. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/tests/test_edit.py +0 -0
  33. {scriptvault-0.2.1b0 → scriptvault-0.4.0}/tests/test_real.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: scriptvault
3
- Version: 0.2.1b0
3
+ Version: 0.4.0
4
4
  Summary: Store and run project commands in a hidden vault directory
5
5
  Author: Majwt
6
6
  License-Expression: MIT
@@ -16,6 +16,7 @@ Description-Content-Type: text/markdown
16
16
  License-File: LICENSE
17
17
  Provides-Extra: dev
18
18
  Requires-Dist: pytest>=8; extra == "dev"
19
+ Requires-Dist: flake8>=7; extra == "dev"
19
20
  Dynamic: license-file
20
21
 
21
22
  # ScriptVault (`sv`)
@@ -40,6 +41,10 @@ From a checkout:
40
41
  pipx install --editable .
41
42
  ```
42
43
 
44
+ For maintainers, `sv set-version 0.4.0` sets the version in `pyproject.toml`
45
+ and `src/scriptvault/__init__.py`. It uses the project environment created by
46
+ `sv build` and rejects invalid versions before changing either file.
47
+
43
48
  ## Quick start
44
49
 
45
50
  Initialize a vault in a project directory:
@@ -68,6 +73,8 @@ List targets:
68
73
  sv list
69
74
  ```
70
75
 
76
+ Running `sv` with no arguments prints the usage and every runnable target.
77
+
71
78
  ## Vault layout
72
79
 
73
80
  ```text
@@ -75,6 +82,7 @@ sv list
75
82
  .sv/
76
83
  vault.toml
77
84
  .env
85
+ GUIDE.md
78
86
  scripts/
79
87
  hello.sh
80
88
  hello.env
@@ -88,6 +96,7 @@ sv list
88
96
 
89
97
  - `vault.toml` defines inline scripts, orchestrations, and nested vault includes.
90
98
  - `.env` is the global dotenv file.
99
+ - `GUIDE.md` is the generated reference (see [Guide](#guide)).
91
100
  - `scripts/*.sh` are executable file scripts.
92
101
  - `scripts/NAME.env` is the per-script dotenv file.
93
102
  - `[include.NAME]` sections load scripts from nested vaults (see below).
@@ -114,7 +123,15 @@ sv run c-hello build
114
123
  sv c-hello build
115
124
  ```
116
125
 
117
- Implied run (`sv deploy`) only works for root vault scripts.
126
+ or with the qualified `include:target` form, which names one include
127
+ explicitly (useful when two includes define the same target):
128
+
129
+ ```bash
130
+ sv run c-hello:build
131
+ sv c-hello:build
132
+ ```
133
+
134
+ Implied run (`sv deploy`) works for plain and qualified target names.
118
135
 
119
136
  ## Scripts
120
137
 
@@ -127,6 +144,23 @@ A file at `.sv/scripts/hello.sh` becomes `sv hello`.
127
144
  echo "Hello from $SV_NAME"
128
145
  ```
129
146
 
147
+ File-script metadata can be defined without `cmd`:
148
+
149
+ ```toml
150
+ [scripts.hello]
151
+ description = "Print a greeting"
152
+ ```
153
+
154
+ This requires a same-name script file in `.sv/scripts/`, such as `hello` or
155
+ `hello.sh`, with a shebang. Without a matching file, `cmd` is required.
156
+
157
+ Scripts and orchestrations accept either `desc` or `description`. If both are
158
+ set, `description` takes precedence. Descriptions are shown beside names in
159
+ `sv list`.
160
+
161
+ Listings use colors on supported terminals. Piped output, JSON, `TERM=dumb`,
162
+ and environments with `NO_COLOR` set remain plain.
163
+
130
164
  ### Inline scripts
131
165
 
132
166
  Define a command in `vault.toml`:
@@ -143,6 +177,49 @@ sv add hello
143
177
  sv add hello --in < script.sh
144
178
  ```
145
179
 
180
+ ### Local And Hidden Scripts
181
+
182
+ ```sh
183
+ sv add personal --local
184
+ sv add personal --local --in < script.sh
185
+ sv run personal
186
+ sv list --all
187
+ ```
188
+
189
+ Local scripts live in `.sv/local/scripts/`. `sv init` and `sv add --local`
190
+ ensure `.sv/.gitignore` ignores `/local/`, preserving existing ignore rules.
191
+ Local scripts are hidden from `sv list` by default but remain callable by
192
+ name, including from orchestration steps. Local and shared names must not
193
+ conflict. Gitignore rules do not untrack files already committed.
194
+
195
+ Shared helpers can also be hidden:
196
+
197
+ ```toml
198
+ [scripts.helper]
199
+ hidden = true
200
+ cmd = "echo helper"
201
+ ```
202
+
203
+ `hidden = true` also works for file-script metadata and orchestrations.
204
+ `sv list --all` reveals hidden targets, including with `--json` or `--nested`.
205
+ Hiding is a listing preference, not access control or secret protection.
206
+
207
+ ### Source-Only Helpers
208
+
209
+ Put reusable shell helpers in `.sv/lib/`, outside the runnable script directory:
210
+
211
+ ```bash
212
+ source "$SV_LIB/helper.sh"
213
+ source "$SV_TOP_LIB/git-version.sh"
214
+ ```
215
+
216
+ `SV_LIB` points to the owning vault's library directory. `SV_TOP_LIB` points
217
+ to the outermost vault's library directory in the current execution chain.
218
+ If a nested vault is invoked on its own, both point to that nested vault's
219
+ library. These paths are injected even when the directories do not yet exist.
220
+ Helpers are not runnable targets and never appear in `sv list`, even with
221
+ `--all`. Sourcing keeps their functions and variables in the calling shell.
222
+
146
223
  ## Running targets
147
224
 
148
225
  ```sh
@@ -174,6 +251,22 @@ sv ci
174
251
 
175
252
  Orchestrations can call scripts and other orchestrations. `sv` detects cycles and reports them.
176
253
 
254
+ ## Interrupting runs
255
+
256
+ Scripts that run until `^C` (servers, watchers, `dotnet` HTTP apps) get the
257
+ interrupt directly: `sv` and its children share the terminal's process group,
258
+ and `sv` itself ignores the first `^C` so the script can shut down. `sv` then
259
+ exits with the script's exit code.
260
+
261
+ If the script hangs during shutdown, press `^C` a second time: `sv` kills every
262
+ child it started and exits with code 130. A `^C` while no script is running
263
+ also exits with 130.
264
+
265
+ ```sh
266
+ sv serve # first ^C: the server stops, sv waits and exits with its code
267
+ # second ^C: sv kills the server and exits 130
268
+ ```
269
+
177
270
  ## Environment
178
271
 
179
272
  Environment files are dotenv-style `KEY=VALUE` files.
@@ -187,8 +280,11 @@ Precedence, from lowest to highest:
187
280
 
188
281
  Injected variables:
189
282
 
190
- - `SV_ROOT`: project root
191
- - `SV_DIR`: `.sv` directory
283
+ - `SV_TOP_ROOT`: outermost vault's root directory in the execution chain
284
+ - `SV_TOP_LIB`: that outermost vault's `.sv/lib` directory
285
+ - `SV_ROOT`: root directory of the vault owning the current script or orchestration
286
+ - `SV_DIR`: that owning vault's `.sv` directory
287
+ - `SV_LIB`: that owning vault's `.sv/lib` directory
192
288
  - `SV_CWD`: current working directory at invocation
193
289
  - `SV_NAME`: target name, when running a named script
194
290
 
@@ -257,10 +353,22 @@ sv completion fish | source
257
353
  ## Help
258
354
 
259
355
  ```sh
260
- sv help
356
+ sv # usage plus every runnable target
357
+ sv help # usage only
261
358
  sv --version
262
359
  ```
263
360
 
361
+ ## Guide
362
+
363
+ `sv init` writes `.sv/GUIDE.md`, a reference for scripts, orchestrations,
364
+ nested vaults, and environment injection. The guide is stamped with the sv
365
+ version that generated it:
366
+
367
+ ```sh
368
+ sv guide # rewrite it only when that stamp is older than this sv
369
+ sv guide --force # rewrite it either way
370
+ ```
371
+
264
372
  ## Documentation
265
373
 
266
374
  For detailed guides and documentation:
@@ -20,6 +20,10 @@ From a checkout:
20
20
  pipx install --editable .
21
21
  ```
22
22
 
23
+ For maintainers, `sv set-version 0.4.0` sets the version in `pyproject.toml`
24
+ and `src/scriptvault/__init__.py`. It uses the project environment created by
25
+ `sv build` and rejects invalid versions before changing either file.
26
+
23
27
  ## Quick start
24
28
 
25
29
  Initialize a vault in a project directory:
@@ -48,6 +52,8 @@ List targets:
48
52
  sv list
49
53
  ```
50
54
 
55
+ Running `sv` with no arguments prints the usage and every runnable target.
56
+
51
57
  ## Vault layout
52
58
 
53
59
  ```text
@@ -55,6 +61,7 @@ sv list
55
61
  .sv/
56
62
  vault.toml
57
63
  .env
64
+ GUIDE.md
58
65
  scripts/
59
66
  hello.sh
60
67
  hello.env
@@ -68,6 +75,7 @@ sv list
68
75
 
69
76
  - `vault.toml` defines inline scripts, orchestrations, and nested vault includes.
70
77
  - `.env` is the global dotenv file.
78
+ - `GUIDE.md` is the generated reference (see [Guide](#guide)).
71
79
  - `scripts/*.sh` are executable file scripts.
72
80
  - `scripts/NAME.env` is the per-script dotenv file.
73
81
  - `[include.NAME]` sections load scripts from nested vaults (see below).
@@ -94,7 +102,15 @@ sv run c-hello build
94
102
  sv c-hello build
95
103
  ```
96
104
 
97
- Implied run (`sv deploy`) only works for root vault scripts.
105
+ or with the qualified `include:target` form, which names one include
106
+ explicitly (useful when two includes define the same target):
107
+
108
+ ```bash
109
+ sv run c-hello:build
110
+ sv c-hello:build
111
+ ```
112
+
113
+ Implied run (`sv deploy`) works for plain and qualified target names.
98
114
 
99
115
  ## Scripts
100
116
 
@@ -107,6 +123,23 @@ A file at `.sv/scripts/hello.sh` becomes `sv hello`.
107
123
  echo "Hello from $SV_NAME"
108
124
  ```
109
125
 
126
+ File-script metadata can be defined without `cmd`:
127
+
128
+ ```toml
129
+ [scripts.hello]
130
+ description = "Print a greeting"
131
+ ```
132
+
133
+ This requires a same-name script file in `.sv/scripts/`, such as `hello` or
134
+ `hello.sh`, with a shebang. Without a matching file, `cmd` is required.
135
+
136
+ Scripts and orchestrations accept either `desc` or `description`. If both are
137
+ set, `description` takes precedence. Descriptions are shown beside names in
138
+ `sv list`.
139
+
140
+ Listings use colors on supported terminals. Piped output, JSON, `TERM=dumb`,
141
+ and environments with `NO_COLOR` set remain plain.
142
+
110
143
  ### Inline scripts
111
144
 
112
145
  Define a command in `vault.toml`:
@@ -123,6 +156,49 @@ sv add hello
123
156
  sv add hello --in < script.sh
124
157
  ```
125
158
 
159
+ ### Local And Hidden Scripts
160
+
161
+ ```sh
162
+ sv add personal --local
163
+ sv add personal --local --in < script.sh
164
+ sv run personal
165
+ sv list --all
166
+ ```
167
+
168
+ Local scripts live in `.sv/local/scripts/`. `sv init` and `sv add --local`
169
+ ensure `.sv/.gitignore` ignores `/local/`, preserving existing ignore rules.
170
+ Local scripts are hidden from `sv list` by default but remain callable by
171
+ name, including from orchestration steps. Local and shared names must not
172
+ conflict. Gitignore rules do not untrack files already committed.
173
+
174
+ Shared helpers can also be hidden:
175
+
176
+ ```toml
177
+ [scripts.helper]
178
+ hidden = true
179
+ cmd = "echo helper"
180
+ ```
181
+
182
+ `hidden = true` also works for file-script metadata and orchestrations.
183
+ `sv list --all` reveals hidden targets, including with `--json` or `--nested`.
184
+ Hiding is a listing preference, not access control or secret protection.
185
+
186
+ ### Source-Only Helpers
187
+
188
+ Put reusable shell helpers in `.sv/lib/`, outside the runnable script directory:
189
+
190
+ ```bash
191
+ source "$SV_LIB/helper.sh"
192
+ source "$SV_TOP_LIB/git-version.sh"
193
+ ```
194
+
195
+ `SV_LIB` points to the owning vault's library directory. `SV_TOP_LIB` points
196
+ to the outermost vault's library directory in the current execution chain.
197
+ If a nested vault is invoked on its own, both point to that nested vault's
198
+ library. These paths are injected even when the directories do not yet exist.
199
+ Helpers are not runnable targets and never appear in `sv list`, even with
200
+ `--all`. Sourcing keeps their functions and variables in the calling shell.
201
+
126
202
  ## Running targets
127
203
 
128
204
  ```sh
@@ -154,6 +230,22 @@ sv ci
154
230
 
155
231
  Orchestrations can call scripts and other orchestrations. `sv` detects cycles and reports them.
156
232
 
233
+ ## Interrupting runs
234
+
235
+ Scripts that run until `^C` (servers, watchers, `dotnet` HTTP apps) get the
236
+ interrupt directly: `sv` and its children share the terminal's process group,
237
+ and `sv` itself ignores the first `^C` so the script can shut down. `sv` then
238
+ exits with the script's exit code.
239
+
240
+ If the script hangs during shutdown, press `^C` a second time: `sv` kills every
241
+ child it started and exits with code 130. A `^C` while no script is running
242
+ also exits with 130.
243
+
244
+ ```sh
245
+ sv serve # first ^C: the server stops, sv waits and exits with its code
246
+ # second ^C: sv kills the server and exits 130
247
+ ```
248
+
157
249
  ## Environment
158
250
 
159
251
  Environment files are dotenv-style `KEY=VALUE` files.
@@ -167,8 +259,11 @@ Precedence, from lowest to highest:
167
259
 
168
260
  Injected variables:
169
261
 
170
- - `SV_ROOT`: project root
171
- - `SV_DIR`: `.sv` directory
262
+ - `SV_TOP_ROOT`: outermost vault's root directory in the execution chain
263
+ - `SV_TOP_LIB`: that outermost vault's `.sv/lib` directory
264
+ - `SV_ROOT`: root directory of the vault owning the current script or orchestration
265
+ - `SV_DIR`: that owning vault's `.sv` directory
266
+ - `SV_LIB`: that owning vault's `.sv/lib` directory
172
267
  - `SV_CWD`: current working directory at invocation
173
268
  - `SV_NAME`: target name, when running a named script
174
269
 
@@ -237,10 +332,22 @@ sv completion fish | source
237
332
  ## Help
238
333
 
239
334
  ```sh
240
- sv help
335
+ sv # usage plus every runnable target
336
+ sv help # usage only
241
337
  sv --version
242
338
  ```
243
339
 
340
+ ## Guide
341
+
342
+ `sv init` writes `.sv/GUIDE.md`, a reference for scripts, orchestrations,
343
+ nested vaults, and environment injection. The guide is stamped with the sv
344
+ version that generated it:
345
+
346
+ ```sh
347
+ sv guide # rewrite it only when that stamp is older than this sv
348
+ sv guide --force # rewrite it either way
349
+ ```
350
+
244
351
  ## Documentation
245
352
 
246
353
  For detailed guides and documentation:
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "scriptvault"
7
- version = "0.2.1b0"
7
+ version = "0.4.0"
8
8
  description = "Store and run project commands in a hidden vault directory"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -24,10 +24,10 @@ classifiers = [
24
24
  sv = "scriptvault.cli:main"
25
25
 
26
26
  [project.optional-dependencies]
27
- dev = ["pytest>=8"]
27
+ dev = ["pytest>=8", "flake8>=7"]
28
28
 
29
29
  [dependency-groups]
30
- dev = ["pytest>=8"]
30
+ dev = ["pytest>=8", "flake8>=7"]
31
31
 
32
32
  [tool.setuptools.packages.find]
33
33
  where = ["src"]
@@ -0,0 +1,8 @@
1
+ """ScriptVault: store and run project commands in a hidden vault directory."""
2
+
3
+ from importlib.metadata import PackageNotFoundError
4
+
5
+ try:
6
+ __version__ = "0.4.0"
7
+ except PackageNotFoundError:
8
+ __version__ = "0.4.0"