scriptvault 0.4.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.4.0/src/scriptvault.egg-info → scriptvault-0.6.0}/PKG-INFO +56 -4
  2. {scriptvault-0.4.0 → scriptvault-0.6.0}/README.md +55 -3
  3. {scriptvault-0.4.0 → scriptvault-0.6.0}/pyproject.toml +1 -1
  4. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault/__init__.py +2 -2
  5. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault/cli.py +63 -24
  6. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault/run.py +93 -30
  7. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault/templates.py +41 -6
  8. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault/vault.py +245 -178
  9. {scriptvault-0.4.0 → scriptvault-0.6.0/src/scriptvault.egg-info}/PKG-INFO +56 -4
  10. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault.egg-info/SOURCES.txt +1 -0
  11. {scriptvault-0.4.0 → scriptvault-0.6.0}/tests/test_add.py +25 -2
  12. {scriptvault-0.4.0 → scriptvault-0.6.0}/tests/test_edit.py +13 -0
  13. {scriptvault-0.4.0 → scriptvault-0.6.0}/tests/test_init.py +30 -0
  14. {scriptvault-0.4.0 → scriptvault-0.6.0}/tests/test_list.py +1 -0
  15. scriptvault-0.6.0/tests/test_local_vault.py +276 -0
  16. {scriptvault-0.4.0 → scriptvault-0.6.0}/tests/test_run.py +251 -1
  17. {scriptvault-0.4.0 → scriptvault-0.6.0}/LICENSE +0 -0
  18. {scriptvault-0.4.0 → scriptvault-0.6.0}/setup.cfg +0 -0
  19. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault/__main__.py +0 -0
  20. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault/envfile.py +0 -0
  21. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault/term.py +0 -0
  22. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault.egg-info/dependency_links.txt +0 -0
  23. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault.egg-info/entry_points.txt +0 -0
  24. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault.egg-info/requires.txt +0 -0
  25. {scriptvault-0.4.0 → scriptvault-0.6.0}/src/scriptvault.egg-info/top_level.txt +0 -0
  26. {scriptvault-0.4.0 → scriptvault-0.6.0}/tests/test_completion.py +0 -0
  27. {scriptvault-0.4.0 → scriptvault-0.6.0}/tests/test_guide.py +0 -0
  28. {scriptvault-0.4.0 → scriptvault-0.6.0}/tests/test_hooks.py +0 -0
  29. {scriptvault-0.4.0 → scriptvault-0.6.0}/tests/test_real.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: scriptvault
3
- Version: 0.4.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/
@@ -161,6 +164,13 @@ set, `description` takes precedence. Descriptions are shown beside names in
161
164
  Listings use colors on supported terminals. Piped output, JSON, `TERM=dumb`,
162
165
  and environments with `NO_COLOR` set remain plain.
163
166
 
167
+ On macOS/Linux, captured orchestration and parallel output uses a
168
+ pseudo-terminal (PTY) when the output terminal supports color, so child
169
+ commands retain their automatic colors. Stdin and signal handling remain
170
+ unchanged. Redirected output, `NO_COLOR`, `TERM=dumb`, Windows and unavailable
171
+ PTYs use normal pipes instead. Explicit force-color settings in child commands
172
+ still apply.
173
+
164
174
  ### Inline scripts
165
175
 
166
176
  Define a command in `vault.toml`:
@@ -188,8 +198,9 @@ sv list --all
188
198
 
189
199
  Local scripts live in `.sv/local/scripts/`. `sv init` and `sv add --local`
190
200
  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
201
+ Local scripts appear in `sv list` by default; use `hidden = true` to hide
202
+ them. `.sv/local/scripts/NAME.env` supplies per-script environment variables.
203
+ Local and shared names must not
193
204
  conflict. Gitignore rules do not untrack files already committed.
194
205
 
195
206
  Shared helpers can also be hidden:
@@ -204,6 +215,46 @@ cmd = "echo helper"
204
215
  `sv list --all` reveals hidden targets, including with `--json` or `--nested`.
205
216
  Hiding is a listing preference, not access control or secret protection.
206
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
+
207
258
  ### Source-Only Helpers
208
259
 
209
260
  Put reusable shell helpers in `.sv/lib/`, outside the runnable script directory:
@@ -274,7 +325,7 @@ Environment files are dotenv-style `KEY=VALUE` files.
274
325
  Precedence, from lowest to highest:
275
326
 
276
327
  1. `.sv/.env`
277
- 2. `.sv/scripts/NAME.env`
328
+ 2. `.sv/scripts/NAME.env`, or `.sv/local/scripts/NAME.env` for local scripts
278
329
  3. The real environment
279
330
  4. Injected `SV_*` variables
280
331
 
@@ -321,6 +372,7 @@ Edit the global vault config or global env:
321
372
  ```sh
322
373
  sv edit config
323
374
  sv edit env
375
+ sv edit local
324
376
  ```
325
377
 
326
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/
@@ -140,6 +143,13 @@ set, `description` takes precedence. Descriptions are shown beside names in
140
143
  Listings use colors on supported terminals. Piped output, JSON, `TERM=dumb`,
141
144
  and environments with `NO_COLOR` set remain plain.
142
145
 
146
+ On macOS/Linux, captured orchestration and parallel output uses a
147
+ pseudo-terminal (PTY) when the output terminal supports color, so child
148
+ commands retain their automatic colors. Stdin and signal handling remain
149
+ unchanged. Redirected output, `NO_COLOR`, `TERM=dumb`, Windows and unavailable
150
+ PTYs use normal pipes instead. Explicit force-color settings in child commands
151
+ still apply.
152
+
143
153
  ### Inline scripts
144
154
 
145
155
  Define a command in `vault.toml`:
@@ -167,8 +177,9 @@ sv list --all
167
177
 
168
178
  Local scripts live in `.sv/local/scripts/`. `sv init` and `sv add --local`
169
179
  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
180
+ Local scripts appear in `sv list` by default; use `hidden = true` to hide
181
+ them. `.sv/local/scripts/NAME.env` supplies per-script environment variables.
182
+ Local and shared names must not
172
183
  conflict. Gitignore rules do not untrack files already committed.
173
184
 
174
185
  Shared helpers can also be hidden:
@@ -183,6 +194,46 @@ cmd = "echo helper"
183
194
  `sv list --all` reveals hidden targets, including with `--json` or `--nested`.
184
195
  Hiding is a listing preference, not access control or secret protection.
185
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
+
186
237
  ### Source-Only Helpers
187
238
 
188
239
  Put reusable shell helpers in `.sv/lib/`, outside the runnable script directory:
@@ -253,7 +304,7 @@ Environment files are dotenv-style `KEY=VALUE` files.
253
304
  Precedence, from lowest to highest:
254
305
 
255
306
  1. `.sv/.env`
256
- 2. `.sv/scripts/NAME.env`
307
+ 2. `.sv/scripts/NAME.env`, or `.sv/local/scripts/NAME.env` for local scripts
257
308
  3. The real environment
258
309
  4. Injected `SV_*` variables
259
310
 
@@ -300,6 +351,7 @@ Edit the global vault config or global env:
300
351
  ```sh
301
352
  sv edit config
302
353
  sv edit env
354
+ sv edit local
303
355
  ```
304
356
 
305
357
  ## Shell completion
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "scriptvault"
7
- version = "0.4.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.4.0"
6
+ __version__ = "0.6.0"
7
7
  except PackageNotFoundError:
8
- __version__ = "0.4.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(
@@ -925,7 +964,7 @@ def build_parser() -> argparse.ArgumentParser:
925
964
  lst.add_argument(
926
965
  "--json", action="store_true", help="output as a JSON object with include info"
927
966
  )
928
- lst.add_argument("--all", action="store_true", help="include hidden and local targets")
967
+ lst.add_argument("--all", action="store_true", help="include hidden targets")
929
968
  lst.add_argument(
930
969
  "--nested", action="store_true",
931
970
  help="show all nested vault scripts (default: only root scripts)"
@@ -985,10 +1024,10 @@ def build_parser() -> argparse.ArgumentParser:
985
1024
  help="read the script body from stdin instead of the template",
986
1025
  )
987
1026
  add.set_defaults(func=cmd_add)
988
- add.add_argument("--local", action="store_true", help="create a gitignored, hidden local script")
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",
@@ -1,6 +1,9 @@
1
1
  """Execution engine for scripts and orchestrations."""
2
2
 
3
3
  import os
4
+ import errno
5
+ import io
6
+ import shutil
4
7
  import signal
5
8
  import subprocess
6
9
  import sys
@@ -241,7 +244,8 @@ def build_env(
241
244
  env.update(parse_env_file(env_path))
242
245
 
243
246
  if name is not None:
244
- script_env = ctx.scripts_dir / f"{name}.env"
247
+ script = ctx.scripts.get(name)
248
+ script_env = script.env_file(ctx) if script is not None else ctx.scripts_dir / f"{name}.env"
245
249
  if script_env.is_file():
246
250
  env.update(parse_env_file(script_env))
247
251
 
@@ -265,19 +269,88 @@ def _script_argv(vault: Vault, script: Script, args: list[str]) -> list[str]:
265
269
  return [vault.shell, "-c", script.cmd, script.name, *args]
266
270
 
267
271
 
272
+ class _PtyReader(io.RawIOBase):
273
+ def __init__(self, descriptor):
274
+ self._descriptor = descriptor
275
+
276
+ def readable(self):
277
+ return True
278
+
279
+ def readinto(self, buffer):
280
+ try:
281
+ data = os.read(self._descriptor, len(buffer))
282
+ except OSError as exc:
283
+ if exc.errno != errno.EIO:
284
+ raise
285
+ data = b""
286
+ buffer[:len(data)] = data
287
+ return len(data)
288
+
289
+ def close(self):
290
+ if not self.closed:
291
+ try:
292
+ os.close(self._descriptor)
293
+ finally:
294
+ super().close()
295
+
296
+
297
+ def _spawn_captured(argv, env, cwd, out, progress):
298
+ terminal = progress._out if progress is not None else out
299
+ use_pty = (
300
+ os.name == "posix"
301
+ and Palette(terminal).enabled
302
+ and "NO_COLOR" not in env
303
+ and env.get("TERM") != "dumb"
304
+ )
305
+ master = slave = None
306
+ if use_pty:
307
+ import termios
308
+
309
+ try:
310
+ master, slave = os.openpty()
311
+ attributes = termios.tcgetattr(slave)
312
+ attributes[1] &= ~termios.OPOST
313
+ termios.tcsetattr(slave, termios.TCSANOW, attributes)
314
+ try:
315
+ size = os.get_terminal_size(terminal.fileno())
316
+ except (AttributeError, OSError, ValueError):
317
+ size = shutil.get_terminal_size()
318
+ termios.tcsetwinsize(slave, (size.lines, size.columns))
319
+ except (OSError, termios.error):
320
+ if master is not None:
321
+ os.close(master)
322
+ if slave is not None:
323
+ os.close(slave)
324
+ master = slave = None
325
+ try:
326
+ proc = subprocess.Popen(
327
+ argv,
328
+ cwd=str(cwd),
329
+ env=env,
330
+ stdout=slave if slave is not None else subprocess.PIPE,
331
+ stderr=subprocess.STDOUT,
332
+ text=True,
333
+ encoding="utf-8",
334
+ errors="replace",
335
+ )
336
+ except BaseException:
337
+ if master is not None:
338
+ os.close(master)
339
+ raise
340
+ finally:
341
+ if slave is not None:
342
+ os.close(slave)
343
+ if master is not None:
344
+ proc.stdout = io.TextIOWrapper(
345
+ io.BufferedReader(_PtyReader(master)), encoding="utf-8", errors="replace", newline=""
346
+ )
347
+ return proc
348
+
349
+
268
350
  def _run_child(argv: list[str], env: dict[str, str], cwd, out, progress):
269
351
  if out is None:
270
352
  out = sys.stdout
271
- proc = subprocess.Popen(
272
- argv,
273
- cwd=str(cwd),
274
- env=env,
275
- stdout=subprocess.PIPE,
276
- stderr=subprocess.STDOUT,
277
- text=True,
278
- encoding="utf-8",
279
- errors="replace",
280
- )
353
+ proc = _spawn_captured(argv, env, cwd, out, progress)
281
354
  _GUARD.add(proc)
282
355
  try:
283
356
  stdout = proc.stdout
@@ -452,22 +525,13 @@ def run_parallel(
452
525
  if global_flags is not None:
453
526
  argv = global_flags + argv
454
527
  cwd = target_vault.root if target_vault else vault.root
455
- proc = subprocess.Popen(
456
- argv,
457
- cwd=str(cwd),
458
- env=env,
459
- stdout=subprocess.PIPE,
460
- stderr=subprocess.STDOUT,
461
- text=True,
462
- encoding="utf-8",
463
- errors="replace",
464
- )
528
+ proc = _spawn_captured(argv, env, cwd, out, progress)
465
529
  procs.append(proc)
466
530
  _GUARD.add(proc)
467
531
  stream = proc.stdout
468
532
  else:
469
533
  rfd, wfd = os.pipe()
470
- stream = os.fdopen(rfd, "r", encoding="utf-8", errors="replace")
534
+ stream = os.fdopen(rfd, "r", encoding="utf-8", errors="replace", newline="")
471
535
  job_out = os.fdopen(wfd, "w", encoding="utf-8", errors="replace")
472
536
  codes = []
473
537
 
@@ -502,16 +566,15 @@ def run_parallel(
502
566
  except KeyboardInterrupt:
503
567
  for proc in procs:
504
568
  _kill_and_reap(proc)
569
+ raise
570
+ finally:
505
571
  for proc in procs:
506
572
  _GUARD.discard(proc)
507
- raise
508
- for proc in procs:
509
- _GUARD.discard(proc)
510
- try:
511
- if proc.stdout is not None:
512
- proc.stdout.close()
513
- except Exception:
514
- pass
573
+ try:
574
+ if proc.stdout is not None:
575
+ proc.stdout.close()
576
+ except Exception:
577
+ pass
515
578
 
516
579
  codes = [proc.returncode for proc in procs]
517
580
  for _, job_codes in jobs:
@@ -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,7 +54,9 @@ 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
56
- .sv/local/scripts/NAME gitignored local script, hidden by default
57
+ .sv/local/vault.toml gitignored overlay of vault.toml (local values win)
58
+ .sv/local/scripts/NAME gitignored local script, listed by default
59
+ .sv/local/scripts/NAME.env environment for that local script
57
60
  .sv/.gitignore ignores /local/
58
61
  .sv/lib/NAME.sh source-only helper, not a runnable target
59
62
  ```
@@ -101,6 +104,13 @@ set, `description` takes precedence. Descriptions are shown beside names in
101
104
  Listings use colors on supported terminals. Piped output, JSON, `TERM=dumb`,
102
105
  and environments with `NO_COLOR` set remain plain.
103
106
 
107
+ On macOS/Linux, captured orchestration and parallel output uses a
108
+ pseudo-terminal (PTY) when the output terminal supports color, so child
109
+ commands retain their automatic colors. Stdin and signal handling remain
110
+ unchanged. Redirected output, `NO_COLOR`, `TERM=dumb`, Windows and unavailable
111
+ PTYs use normal pipes instead. Explicit force-color settings in child commands
112
+ still apply.
113
+
104
114
  ## Running
105
115
 
106
116
  ```sh
@@ -110,13 +120,14 @@ sv run build --release # arguments go to the script
110
120
  sv run build -- --flag # `--` when an argument could look like an sv flag
111
121
 
112
122
  sv list # show visible targets
113
- sv list --all # include hidden and local targets
123
+ sv list --all # include hidden targets
114
124
  sv guide # refresh .sv/GUIDE.md when sv is newer than it
115
125
  sv add deploy # create .sv/scripts/deploy.sh
116
126
  sv add personal --local # create .sv/local/scripts/personal.sh
117
127
  sv edit deploy # open the script, or its vault.toml entry
118
128
  sv edit deploy env # open .sv/scripts/deploy.env
119
129
  sv edit config # open vault.toml
130
+ sv edit local # open .sv/local/vault.toml (creates it if missing)
120
131
  sv edit env # open .sv/.env
121
132
  sv help
122
133
  ```
@@ -125,10 +136,34 @@ sv help
125
136
 
126
137
  `sv add NAME --local` creates an executable script in `.sv/local/scripts/`
127
138
  and ensures `.sv/.gitignore` ignores `/local/`. Existing ignore rules are
128
- preserved. Local scripts are hidden from listings by default, but `sv NAME`
129
- and orchestration steps can still call them. Local and shared names must not
139
+ preserved. Local scripts are listed by default; use `hidden = true` to hide
140
+ them. Their adjacent `.env` files are loaded automatically. Local and shared names must not
130
141
  conflict. Gitignore rules do not untrack files already committed.
131
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
+
132
167
  Shared helpers can be hidden with metadata:
133
168
 
134
169
  ```toml
@@ -230,7 +265,7 @@ Sources are applied in this order, so later ones win:
230
265
  1. `.sv/.env` - vault-wide defaults
231
266
  2. `.env` of every included vault (in include order), then `.env` in the
232
267
  project root
233
- 3. `.sv/scripts/NAME.env` - one file per script
268
+ 3. `.sv/scripts/NAME.env`, or `.sv/local/scripts/NAME.env` for local scripts
234
269
  4. the real environment (your shell)
235
270
  5. injected `SV_*` variables:
236
271
  - `SV_TOP_ROOT` - outermost vault's root directory in the execution chain