scriptvault 0.5.0__tar.gz → 0.6.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 (29) hide show
  1. {scriptvault-0.5.0/src/scriptvault.egg-info → scriptvault-0.6.0}/PKG-INFO +45 -1
  2. {scriptvault-0.5.0 → scriptvault-0.6.0}/README.md +44 -0
  3. {scriptvault-0.5.0 → scriptvault-0.6.0}/pyproject.toml +1 -1
  4. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault/__init__.py +2 -2
  5. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault/cli.py +61 -22
  6. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault/templates.py +28 -1
  7. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault/vault.py +243 -177
  8. {scriptvault-0.5.0 → scriptvault-0.6.0/src/scriptvault.egg-info}/PKG-INFO +45 -1
  9. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault.egg-info/SOURCES.txt +1 -0
  10. {scriptvault-0.5.0 → scriptvault-0.6.0}/tests/test_init.py +30 -0
  11. scriptvault-0.6.0/tests/test_local_vault.py +276 -0
  12. {scriptvault-0.5.0 → scriptvault-0.6.0}/LICENSE +0 -0
  13. {scriptvault-0.5.0 → scriptvault-0.6.0}/setup.cfg +0 -0
  14. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault/__main__.py +0 -0
  15. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault/envfile.py +0 -0
  16. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault/run.py +0 -0
  17. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault/term.py +0 -0
  18. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault.egg-info/dependency_links.txt +0 -0
  19. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault.egg-info/entry_points.txt +0 -0
  20. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault.egg-info/requires.txt +0 -0
  21. {scriptvault-0.5.0 → scriptvault-0.6.0}/src/scriptvault.egg-info/top_level.txt +0 -0
  22. {scriptvault-0.5.0 → scriptvault-0.6.0}/tests/test_add.py +0 -0
  23. {scriptvault-0.5.0 → scriptvault-0.6.0}/tests/test_completion.py +0 -0
  24. {scriptvault-0.5.0 → scriptvault-0.6.0}/tests/test_edit.py +0 -0
  25. {scriptvault-0.5.0 → scriptvault-0.6.0}/tests/test_guide.py +0 -0
  26. {scriptvault-0.5.0 → scriptvault-0.6.0}/tests/test_hooks.py +0 -0
  27. {scriptvault-0.5.0 → scriptvault-0.6.0}/tests/test_list.py +0 -0
  28. {scriptvault-0.5.0 → scriptvault-0.6.0}/tests/test_real.py +0 -0
  29. {scriptvault-0.5.0 → scriptvault-0.6.0}/tests/test_run.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: scriptvault
3
- Version: 0.5.0
3
+ Version: 0.6.0
4
4
  Summary: Store and run project commands in a hidden vault directory
5
5
  Author: Majwt
6
6
  License-Expression: MIT
@@ -86,6 +86,9 @@ Running `sv` with no arguments prints the usage and every runnable target.
86
86
  scripts/
87
87
  hello.sh
88
88
  hello.env
89
+ local/
90
+ vault.toml
91
+ scripts/
89
92
  includes/
90
93
  c-hello/
91
94
  .sv/
@@ -212,6 +215,46 @@ cmd = "echo helper"
212
215
  `sv list --all` reveals hidden targets, including with `--json` or `--nested`.
213
216
  Hiding is a listing preference, not access control or secret protection.
214
217
 
218
+ ### Local Vault
219
+
220
+ `.sv/local/vault.toml` is an optional, gitignored overlay of `.sv/vault.toml`
221
+ using the same tables. It is parsed after the committed file, so local values
222
+ win:
223
+
224
+ - `[vault]` — `shell` and `environment` (and `name`, which must match if set)
225
+ - `[scripts]` — add or override inline scripts
226
+ - `[orchestrate]` — add or override orchestrations
227
+ - `[include]` — add includes (aliases must not collide with committed ones)
228
+
229
+ This is the escape hatch for personal, non-committed orchestrations:
230
+
231
+ ```toml
232
+ # .sv/local/vault.toml
233
+ [scripts.personal-greet]
234
+ cmd = "echo hello from local overlay"
235
+
236
+ [orchestrate.mybuild]
237
+ description = "Personal build pipeline"
238
+ steps = [
239
+ { run = "build" },
240
+ { run = "personal-greet" },
241
+ ]
242
+ ```
243
+
244
+ Open it with `sv edit local` (creates the file if missing).
245
+
246
+ #### Fully Local Vault
247
+
248
+ A project does not need a committed `.sv/` at all. `sv init --local` (or just
249
+ creating `.sv/local/vault.toml`) makes a vault that lives entirely under
250
+ `.sv/local/`, so a single global gitignore entry (`.sv/local/`) lets you use
251
+ `sv` in repositories that know nothing about it. The `[vault]` name defaults
252
+ to the directory name. In this mode `.sv/local/` plays the role of `.sv/`:
253
+ `scripts/`, `.env`, `hooks/`, `git-hooks.toml` and `GUIDE.md` all live there,
254
+ and `sv add` writes to `.sv/local/scripts/` (`--local` is implied). Every
255
+ command works as in a committed vault. If `.sv/vault.toml` is added later, the
256
+ local file becomes an overlay again.
257
+
215
258
  ### Source-Only Helpers
216
259
 
217
260
  Put reusable shell helpers in `.sv/lib/`, outside the runnable script directory:
@@ -329,6 +372,7 @@ Edit the global vault config or global env:
329
372
  ```sh
330
373
  sv edit config
331
374
  sv edit env
375
+ sv edit local
332
376
  ```
333
377
 
334
378
  ## Shell completion
@@ -65,6 +65,9 @@ Running `sv` with no arguments prints the usage and every runnable target.
65
65
  scripts/
66
66
  hello.sh
67
67
  hello.env
68
+ local/
69
+ vault.toml
70
+ scripts/
68
71
  includes/
69
72
  c-hello/
70
73
  .sv/
@@ -191,6 +194,46 @@ cmd = "echo helper"
191
194
  `sv list --all` reveals hidden targets, including with `--json` or `--nested`.
192
195
  Hiding is a listing preference, not access control or secret protection.
193
196
 
197
+ ### Local Vault
198
+
199
+ `.sv/local/vault.toml` is an optional, gitignored overlay of `.sv/vault.toml`
200
+ using the same tables. It is parsed after the committed file, so local values
201
+ win:
202
+
203
+ - `[vault]` — `shell` and `environment` (and `name`, which must match if set)
204
+ - `[scripts]` — add or override inline scripts
205
+ - `[orchestrate]` — add or override orchestrations
206
+ - `[include]` — add includes (aliases must not collide with committed ones)
207
+
208
+ This is the escape hatch for personal, non-committed orchestrations:
209
+
210
+ ```toml
211
+ # .sv/local/vault.toml
212
+ [scripts.personal-greet]
213
+ cmd = "echo hello from local overlay"
214
+
215
+ [orchestrate.mybuild]
216
+ description = "Personal build pipeline"
217
+ steps = [
218
+ { run = "build" },
219
+ { run = "personal-greet" },
220
+ ]
221
+ ```
222
+
223
+ Open it with `sv edit local` (creates the file if missing).
224
+
225
+ #### Fully Local Vault
226
+
227
+ A project does not need a committed `.sv/` at all. `sv init --local` (or just
228
+ creating `.sv/local/vault.toml`) makes a vault that lives entirely under
229
+ `.sv/local/`, so a single global gitignore entry (`.sv/local/`) lets you use
230
+ `sv` in repositories that know nothing about it. The `[vault]` name defaults
231
+ to the directory name. In this mode `.sv/local/` plays the role of `.sv/`:
232
+ `scripts/`, `.env`, `hooks/`, `git-hooks.toml` and `GUIDE.md` all live there,
233
+ and `sv add` writes to `.sv/local/scripts/` (`--local` is implied). Every
234
+ command works as in a committed vault. If `.sv/vault.toml` is added later, the
235
+ local file becomes an overlay again.
236
+
194
237
  ### Source-Only Helpers
195
238
 
196
239
  Put reusable shell helpers in `.sv/lib/`, outside the runnable script directory:
@@ -308,6 +351,7 @@ Edit the global vault config or global env:
308
351
  ```sh
309
352
  sv edit config
310
353
  sv edit env
354
+ sv edit local
311
355
  ```
312
356
 
313
357
  ## Shell completion
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "scriptvault"
7
- version = "0.5.0"
7
+ version = "0.6.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"
@@ -3,6 +3,6 @@
3
3
  from importlib.metadata import PackageNotFoundError
4
4
 
5
5
  try:
6
- __version__ = "0.5.0"
6
+ __version__ = "0.6.0"
7
7
  except PackageNotFoundError:
8
- __version__ = "0.5.0"
8
+ __version__ = "0.6.0"
@@ -22,6 +22,7 @@ from .vault import (
22
22
  VaultError,
23
23
  VaultNotFound,
24
24
  find_root,
25
+ has_vault,
25
26
  hidden_dir_name,
26
27
  load_vault,
27
28
  split_qualified,
@@ -42,7 +43,7 @@ COMMANDS = (
42
43
  "run",
43
44
  )
44
45
  BUILTIN_COMMANDS = set(COMMANDS) | {"__names"}
45
- RESERVED_NAMES = BUILTIN_COMMANDS | {"config", "env"}
46
+ RESERVED_NAMES = BUILTIN_COMMANDS | {"config", "env", "local"}
46
47
 
47
48
 
48
49
  class CLIError(Exception):
@@ -76,16 +77,26 @@ def cmd_init(args: argparse.Namespace) -> int:
76
77
  hidden = root / hidden_dir_name()
77
78
  if hidden.exists() and not hidden.is_dir():
78
79
  raise CLIError(f"'{hidden}' exists and is not a directory")
80
+ if args.local:
81
+ # Fully local vault: nothing outside .sv/local/ is created, so a
82
+ # global gitignore entry for it keeps the project clean.
83
+ hidden = hidden / "local"
79
84
  vault_toml = hidden / "vault.toml"
80
85
  if vault_toml.is_file():
81
86
  raise CLIError(f"a vault already exists at '{vault_toml}'")
87
+ if args.local and (hidden.parent / "vault.toml").is_file():
88
+ raise CLIError(
89
+ f"a committed vault already exists at '{hidden.parent / 'vault.toml'}'; "
90
+ "use 'sv edit local' for a local overlay"
91
+ )
82
92
 
83
93
  name = args.name or root.name
84
94
  if not name:
85
95
  raise CLIError("cannot derive a vault name from path; pass --name")
86
96
 
87
97
  (hidden / "scripts").mkdir(parents=True, exist_ok=True)
88
- _ignore_local_scripts(hidden)
98
+ if not args.local:
99
+ _ignore_local_scripts(hidden)
89
100
  vault_toml.write_text(
90
101
  templates.VAULT_TOML.format(name=_toml_str(name)), encoding="utf-8"
91
102
  )
@@ -615,8 +626,10 @@ def cmd_add(args: argparse.Namespace) -> int:
615
626
  body += "\n"
616
627
 
617
628
  scripts_dir = vault.local_scripts_dir if args.local else vault.scripts_dir
629
+ if vault.local_only:
630
+ scripts_dir = vault.scripts_dir
618
631
  scripts_dir.mkdir(parents=True, exist_ok=True)
619
- if args.local:
632
+ if args.local and not vault.local_only:
620
633
  _ignore_local_scripts(vault.hidden_dir)
621
634
  path = scripts_dir / f"{name}.sh"
622
635
  if path.exists():
@@ -656,15 +669,24 @@ def _run_editor(argv: list[str]) -> int:
656
669
  return 0
657
670
 
658
671
 
659
- def _toml_line(vault, name: str) -> int | None:
660
- """1-based line number of the [scripts.NAME] / [orchestrate.NAME] header."""
661
- lines = vault.vault_toml.read_text(encoding="utf-8").splitlines()
672
+ def _toml_line(vault, name: str) -> tuple[Path, int | None]:
673
+ """Config file and 1-based line of the [scripts.NAME] / [orchestrate.NAME] header.
674
+
675
+ The local overlay wins over the committed file, so it is searched first.
676
+ """
662
677
  exact = {f"[scripts.{name}]", f"[orchestrate.{name}]"}
663
- for i, line in enumerate(lines, 1):
664
- part = line.split("#", 1)[0].strip()
665
- if "".join(part.split()) in exact:
666
- return i
667
- return None
678
+ candidates = [vault.vault_toml]
679
+ if vault.local_vault_toml.is_file():
680
+ candidates.insert(0, vault.local_vault_toml)
681
+ for path in candidates:
682
+ if not path.is_file():
683
+ continue
684
+ lines = path.read_text(encoding="utf-8").splitlines()
685
+ for i, line in enumerate(lines, 1):
686
+ part = line.split("#", 1)[0].strip()
687
+ if "".join(part.split()) in exact:
688
+ return path, i
689
+ return vault.vault_toml, None
668
690
 
669
691
 
670
692
  def _interactive() -> bool:
@@ -677,7 +699,7 @@ def _interactive() -> bool:
677
699
  def _select_target(vault) -> str:
678
700
  """Interactively pick a target (or 'config'/'env') to edit."""
679
701
  choices = list(vault.targets)
680
- for pseudo in ("config", "env"):
702
+ for pseudo in ("config", "env", "local"):
681
703
  if pseudo not in choices:
682
704
  choices.append(pseudo)
683
705
  fzf = shutil.which("fzf")
@@ -717,11 +739,23 @@ def cmd_edit(args: argparse.Namespace) -> int:
717
739
  kind = args.kind
718
740
  if name is None:
719
741
  name = _select_target(vault)
720
- if name in ("config", "env"):
742
+ if name in ("config", "env", "local"):
721
743
  if kind is not None:
722
744
  raise CLIError(f"{name!r} does not take a kind argument")
723
745
  if name == "config":
724
746
  return _run_editor(_editor_argv(vault.vault_toml))
747
+ if name == "local" and vault.local_only:
748
+ return _run_editor(_editor_argv(vault.vault_toml))
749
+ if name == "local":
750
+ local_toml = vault.local_vault_toml
751
+ if not local_toml.exists():
752
+ local_toml.parent.mkdir(parents=True, exist_ok=True)
753
+ local_toml.write_text(
754
+ "# Local vault overlay (.sv/local/vault.toml, gitignored).\n"
755
+ "# Same tables as .sv/vault.toml; local values win.\n",
756
+ encoding="utf-8",
757
+ )
758
+ return _run_editor(_editor_argv(local_toml))
725
759
  return _run_editor(_editor_argv(vault.global_env))
726
760
  target = vault.get(name)
727
761
  if target is None:
@@ -741,14 +775,14 @@ def cmd_edit(args: argparse.Namespace) -> int:
741
775
  return _run_editor(_editor_argv(path))
742
776
  if kind == "config":
743
777
  if isinstance(target, Orchestration) or target.path is None:
744
- line = _toml_line(vault, name)
778
+ toml_path, line = _toml_line(vault, name)
745
779
  else:
746
- line = None
747
- return _run_editor(_editor_argv(vault.vault_toml, line))
780
+ toml_path, line = vault.vault_toml, None
781
+ return _run_editor(_editor_argv(toml_path, line))
748
782
  if isinstance(target, Script) and target.path is not None:
749
783
  return _run_editor(_editor_argv(target.path))
750
- line = _toml_line(vault, name)
751
- return _run_editor(_editor_argv(vault.vault_toml, line))
784
+ toml_path, line = _toml_line(vault, name)
785
+ return _run_editor(_editor_argv(toml_path, line))
752
786
 
753
787
 
754
788
  def _render_completion(template: str) -> str:
@@ -801,9 +835,9 @@ def cmd_activate(args: argparse.Namespace) -> int:
801
835
  current = Path.cwd()
802
836
  hidden = hidden_dir_name()
803
837
  if args.name is None:
804
- if current.name == hidden and (current / "vault.toml").is_file():
838
+ if current.name == hidden and has_vault(current.parent):
805
839
  vault_root = current.parent
806
- elif (current / hidden / "vault.toml").is_file():
840
+ elif has_vault(current):
807
841
  vault_root = current
808
842
  else:
809
843
  print(f"Error: No vault found in {current}", file=sys.stderr)
@@ -814,7 +848,7 @@ def cmd_activate(args: argparse.Namespace) -> int:
814
848
  return 1
815
849
 
816
850
  vault_root = current / args.name
817
- if not (vault_root / hidden / "vault.toml").is_file():
851
+ if not has_vault(vault_root):
818
852
  print(f"Error: Vault '{args.name}' not found", file=sys.stderr)
819
853
  return 1
820
854
 
@@ -879,6 +913,11 @@ def build_parser() -> argparse.ArgumentParser:
879
913
  metavar="NAME",
880
914
  help="vault name (default: the directory name)",
881
915
  )
916
+ init.add_argument(
917
+ "--local",
918
+ action="store_true",
919
+ help="create a fully local vault in .sv/local/ (nothing outside it is written)",
920
+ )
882
921
  init.set_defaults(func=cmd_init)
883
922
 
884
923
  init_hooks = sub.add_parser(
@@ -988,7 +1027,7 @@ def build_parser() -> argparse.ArgumentParser:
988
1027
  add.add_argument("--local", action="store_true", help="create a gitignored local script")
989
1028
 
990
1029
  edit = sub.add_parser(
991
- "edit", help="edit a script, its env, or the vault configuration"
1030
+ "edit", help="edit a script, its env, or the vault configuration (committed or local)"
992
1031
  )
993
1032
  edit.add_argument(
994
1033
  "--path",
@@ -32,7 +32,8 @@ GUIDE_MD = """\
32
32
  Generated by ScriptVault {version}. `sv init` writes it to `.sv/GUIDE.md`, and
33
33
  `sv guide` refreshes it whenever sv is newer than the version stamped above
34
34
  (`sv guide --force` rewrites it either way). Everything below is defined in
35
- `.sv/vault.toml` and `.sv/scripts/`.
35
+ `.sv/vault.toml` (plus the optional, gitignored overlay `.sv/local/vault.toml`)
36
+ and `.sv/scripts/`.
36
37
 
37
38
  ## Installation
38
39
 
@@ -53,6 +54,7 @@ checkout instead.
53
54
  .sv/GUIDE.md this file
54
55
  .sv/scripts/NAME file script, run as `sv NAME`
55
56
  .sv/scripts/NAME.env environment for that one script
57
+ .sv/local/vault.toml gitignored overlay of vault.toml (local values win)
56
58
  .sv/local/scripts/NAME gitignored local script, listed by default
57
59
  .sv/local/scripts/NAME.env environment for that local script
58
60
  .sv/.gitignore ignores /local/
@@ -125,6 +127,7 @@ sv add personal --local # create .sv/local/scripts/personal.sh
125
127
  sv edit deploy # open the script, or its vault.toml entry
126
128
  sv edit deploy env # open .sv/scripts/deploy.env
127
129
  sv edit config # open vault.toml
130
+ sv edit local # open .sv/local/vault.toml (creates it if missing)
128
131
  sv edit env # open .sv/.env
129
132
  sv help
130
133
  ```
@@ -137,6 +140,30 @@ preserved. Local scripts are listed by default; use `hidden = true` to hide
137
140
  them. Their adjacent `.env` files are loaded automatically. Local and shared names must not
138
141
  conflict. Gitignore rules do not untrack files already committed.
139
142
 
143
+ ### Local Vault
144
+
145
+ `.sv/local/vault.toml` is an optional overlay of `.sv/vault.toml` with the
146
+ same tables: `[vault]` (`shell` and `environment`; `name` must match if set),
147
+ `[scripts]`, `[orchestrate]`, and `[include]` (aliases must not collide with
148
+ committed ones). It is loaded after the committed file, so local values win,
149
+ and it is gitignored via `.sv/.gitignore`. Use it for personal, non-committed
150
+ orchestrations and scripts:
151
+
152
+ ```toml
153
+ # .sv/local/vault.toml
154
+ [scripts.personal-greet]
155
+ cmd = "echo hello from local overlay"
156
+
157
+ [orchestrate.mybuild]
158
+ description = "Personal build pipeline"
159
+ steps = [
160
+ { run = "build" },
161
+ { run = "personal-greet" },
162
+ ]
163
+ ```
164
+
165
+ Open it with `sv edit local` (creates the file if missing).
166
+
140
167
  Shared helpers can be hidden with metadata:
141
168
 
142
169
  ```toml