stageyy 0.1.0__py3-none-any.whl

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.
stageyy/__init__.py ADDED
File without changes
stageyy/cli.py ADDED
@@ -0,0 +1,284 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import importlib.metadata
5
+ import sys
6
+ from pathlib import Path
7
+
8
+ from ruamel.yaml import YAML
9
+
10
+ from stageyy.compiler import CompileError, compile_blueprint
11
+
12
+ try:
13
+ __version__ = importlib.metadata.version("stageyy")
14
+ except importlib.metadata.PackageNotFoundError:
15
+ __version__ = "0.1.0.dev0"
16
+
17
+ CONFIG_FILE = Path("stage.yaml")
18
+ OUTPUT_FILE = Path("compose.yaml")
19
+
20
+ META_HEADER = """_meta:
21
+ stages: [dev, staging, prod]
22
+ consts: {}
23
+
24
+ """
25
+
26
+ STARTER_TEMPLATE = """# ==============================================================================
27
+ # stageyy Configuration (stage.yaml)
28
+ # Multi-stage structural blueprint. Version-control this file in Git.
29
+ # ==============================================================================
30
+
31
+ _meta:
32
+ stages: [dev, staging, prod]
33
+ consts:
34
+ # base_env:
35
+ # - DATABASE_URL
36
+ # - REDIS_URL
37
+
38
+ services:
39
+ # api:
40
+ # image: ghcr.io/org/api:${TAG}
41
+ # build:
42
+ # dev:
43
+ # context: .
44
+ # target: development
45
+ # ports:
46
+ # dev:
47
+ # - "8000:8000"
48
+ # prod:
49
+ # - "127.0.0.1:8000:8000"
50
+ # environment:
51
+ # dev:
52
+ # - DATABASE_URL
53
+ # - DEBUG_TOOLBAR
54
+ # staging: ${base_env}
55
+ # prod: ${base_env}
56
+ """
57
+
58
+
59
+ def resolve_output_path(base_path: Path, stage: str, stub: bool) -> Path:
60
+ """Appends .<stage> before the file extension when stub mode is enabled."""
61
+ if not stub:
62
+ return base_path
63
+ return base_path.with_name(f"{base_path.stem}.{stage}{base_path.suffix}")
64
+
65
+
66
+ def atomic_write_if_changed(target_path: Path, new_content: str) -> bool:
67
+ """Writes to file only when content has changed, bypassing redundant mtime updates."""
68
+ if target_path.exists():
69
+ try:
70
+ if target_path.read_text(encoding="utf-8") == new_content:
71
+ return False
72
+ except Exception:
73
+ pass
74
+
75
+ tmp_path = target_path.with_suffix(f"{target_path.suffix}.tmp")
76
+ with open(tmp_path, "w", encoding="utf-8") as f:
77
+ f.write(new_content)
78
+ tmp_path.replace(target_path)
79
+ return True
80
+
81
+
82
+ def run_pipeline(stage: str, stub: bool = False) -> bool:
83
+ """Executes validation, stage compilation, change detection, and atomic writing."""
84
+ if not CONFIG_FILE.is_file():
85
+ print(
86
+ f"\033[31m✖ Error:\033[0m Blueprint file '{CONFIG_FILE}' not found.",
87
+ file=sys.stderr,
88
+ )
89
+ return False
90
+
91
+ try:
92
+ source_text = CONFIG_FILE.read_text(encoding="utf-8")
93
+ rendered = compile_blueprint(source_text, stage)
94
+ except CompileError as e:
95
+ print(f"\033[31m✖ Compile Error:\033[0m {e}", file=sys.stderr)
96
+ return False
97
+ except Exception as e:
98
+ print(
99
+ f"\033[31m✖ Error parsing {CONFIG_FILE.name}:\033[0m {e}", file=sys.stderr
100
+ )
101
+ return False
102
+
103
+ target_path = resolve_output_path(OUTPUT_FILE, stage, stub)
104
+
105
+ try:
106
+ updated = atomic_write_if_changed(target_path, rendered)
107
+ except Exception as e:
108
+ print(
109
+ f"\033[31m✖ Error writing {target_path.name}:\033[0m {e}", file=sys.stderr
110
+ )
111
+ return False
112
+
113
+ if updated:
114
+ print(
115
+ f"updated \033[32m{target_path.name}\033[0m (stage: \033[36m{stage}\033[0m)"
116
+ )
117
+ else:
118
+ print(f"\033[90m{target_path.name} unchanged\033[0m")
119
+
120
+ return True
121
+
122
+
123
+ def cmd_init(compose_file: Path | None = None) -> None:
124
+ """Initializes stage.yaml from a starter template or an existing Compose file."""
125
+ if CONFIG_FILE.exists():
126
+ print(f"\033[33mWarning:\033[0m {CONFIG_FILE.name} already exists.")
127
+ return
128
+
129
+ if compose_file is None:
130
+ print(f"Creating starter {CONFIG_FILE.name}...")
131
+ CONFIG_FILE.write_text(STARTER_TEMPLATE, encoding="utf-8")
132
+ print(
133
+ f"\033[32m✔ Initialized '{CONFIG_FILE.name}'.\033[0m Edit it and run `stagey gen <stage>`."
134
+ )
135
+ return
136
+
137
+ if compose_file.resolve() == CONFIG_FILE.resolve():
138
+ print(
139
+ f"\033[31m✖ Error:\033[0m Cannot initialize '{CONFIG_FILE.name}' from itself.",
140
+ file=sys.stderr,
141
+ )
142
+ sys.exit(1)
143
+
144
+ if not compose_file.is_file():
145
+ print(
146
+ f"\033[31m✖ Error:\033[0m Source file '{compose_file}' not found.",
147
+ file=sys.stderr,
148
+ )
149
+ sys.exit(1)
150
+
151
+ try:
152
+ raw_text = compose_file.read_text(encoding="utf-8")
153
+ yaml = YAML(typ="safe")
154
+ parsed = yaml.load(raw_text)
155
+ except Exception as e:
156
+ print(
157
+ f"\033[31m✖ Error reading '{compose_file}':\033[0m {e}",
158
+ file=sys.stderr,
159
+ )
160
+ sys.exit(1)
161
+
162
+ if not isinstance(parsed, dict):
163
+ print(
164
+ f"\033[31m✖ Error:\033[0m '{compose_file}' must define a top-level YAML mapping.",
165
+ file=sys.stderr,
166
+ )
167
+ sys.exit(1)
168
+
169
+ if "_meta" in parsed:
170
+ print(
171
+ f"\033[31m✖ Error:\033[0m '{compose_file}' already contains a '_meta' block.",
172
+ file=sys.stderr,
173
+ )
174
+ sys.exit(1)
175
+
176
+ CONFIG_FILE.write_text(META_HEADER + raw_text.lstrip(), encoding="utf-8")
177
+ print(
178
+ f"\033[32m✔ Initialized '{CONFIG_FILE.name}' from '{compose_file}'.\033[0m Run `stagey gen <stage>` to compile."
179
+ )
180
+
181
+
182
+ def cmd_watch(stage: str, stub: bool = False) -> None:
183
+ """Watches stage.yaml for changes with debounced execution."""
184
+ from watchfiles import watch
185
+
186
+ print(
187
+ f"\033[36m⚡ Watching {CONFIG_FILE.name} for stage '{stage}' (Ctrl+C to quit)...\033[0m"
188
+ )
189
+ run_pipeline(stage, stub=stub)
190
+
191
+ try:
192
+ for _ in watch(CONFIG_FILE, debounce=150):
193
+ print("\033[33m[Change detected]\033[0m ", end="")
194
+ run_pipeline(stage, stub=stub)
195
+ except KeyboardInterrupt:
196
+ print("\nWatcher stopped.")
197
+
198
+
199
+ def main() -> None:
200
+ parser = argparse.ArgumentParser(
201
+ prog="stagey",
202
+ description="Centralized multi-stage configuration compiler producing static compose.yaml files.",
203
+ )
204
+ parser.add_argument(
205
+ "-v",
206
+ "--version",
207
+ action="version",
208
+ version=f"%(prog)s {__version__}",
209
+ help="Show version and exit.",
210
+ )
211
+ subparsers = parser.add_subparsers(dest="command")
212
+
213
+ # init
214
+ init_parser = subparsers.add_parser(
215
+ "init",
216
+ help=f"Initialize {CONFIG_FILE.name} (starter template or from an existing compose file)",
217
+ )
218
+ init_parser.add_argument(
219
+ "file",
220
+ nargs="?",
221
+ type=Path,
222
+ help="Optional existing Compose YAML file to wrap into stage.yaml",
223
+ )
224
+
225
+ # gen (aliased as generate)
226
+ gen_parser = subparsers.add_parser(
227
+ "gen",
228
+ aliases=["generate"],
229
+ help=f"Generate {OUTPUT_FILE.name} for the specified stage",
230
+ description=f"Generate {OUTPUT_FILE.name} according to values specified by stage.",
231
+ )
232
+ gen_parser.add_argument(
233
+ "stage",
234
+ type=str,
235
+ help="Target stage to extract values from (e.g. dev, staging, prod)",
236
+ )
237
+ gen_parser.add_argument(
238
+ "-s",
239
+ "--stub",
240
+ action="store_true",
241
+ help="Include the stage name in the output filename (e.g. compose.prod.yaml)",
242
+ )
243
+
244
+ # watch
245
+ watch_parser = subparsers.add_parser(
246
+ "watch",
247
+ help=f"Watch {CONFIG_FILE.name} and recompile on save",
248
+ )
249
+ watch_parser.add_argument(
250
+ "stage",
251
+ type=str,
252
+ help="Target stage to watch and compile (e.g. dev, staging, prod)",
253
+ )
254
+ watch_parser.add_argument(
255
+ "-s",
256
+ "--stub",
257
+ action="store_true",
258
+ help="Include the stage name in the output filename (e.g. compose.prod.yaml)",
259
+ )
260
+
261
+ # version
262
+ subparsers.add_parser(
263
+ "version",
264
+ help="Display installed stageyy version",
265
+ )
266
+
267
+ args = parser.parse_args()
268
+
269
+ if args.command == "init":
270
+ cmd_init(compose_file=args.file)
271
+ elif args.command in ("gen", "generate"):
272
+ success = run_pipeline(args.stage, stub=args.stub)
273
+ sys.exit(0 if success else 1)
274
+ elif args.command == "watch":
275
+ cmd_watch(args.stage, stub=args.stub)
276
+ elif args.command == "version":
277
+ print(f"stageyy {__version__}")
278
+ sys.exit(0)
279
+ else:
280
+ parser.print_help()
281
+
282
+
283
+ if __name__ == "__main__":
284
+ main()
stageyy/compiler.py ADDED
@@ -0,0 +1,236 @@
1
+ from __future__ import annotations
2
+
3
+ import copy
4
+ from curses import meta
5
+ import re
6
+ from io import StringIO
7
+ from typing import Any
8
+
9
+ from ruamel.yaml import YAML
10
+ from ruamel.yaml.comments import CommentedMap, CommentedSeq
11
+
12
+ INTERP_RE = re.compile(r"\$\{([a-zA-Z0-9_-]+)\}")
13
+ EXACT_INTERP_RE = re.compile(r"^\$\{([a-zA-Z0-9_-]+)\}$")
14
+
15
+
16
+ class CompileError(Exception):
17
+ """Raised when the blueprint violates structural or stage invariants."""
18
+
19
+
20
+ def _is_empty(value: Any) -> bool:
21
+ if isinstance(value, str) and not value.strip():
22
+ return True
23
+ if isinstance(value, list) and len(value) == 0:
24
+ return True
25
+ return False
26
+
27
+
28
+ def _parse_meta(root: Any) -> tuple[set[str], dict[str, list[str]]]:
29
+ if not isinstance(root, dict) or "_meta" not in root:
30
+ raise CompileError("Root must be a mapping containing a '_meta' block.")
31
+
32
+ meta = root["_meta"]
33
+ if not isinstance(meta, dict):
34
+ raise CompileError("'_meta' must be a mapping.")
35
+
36
+ unknown_meta_keys = set(meta.keys()) - {"stages", "consts"}
37
+ if unknown_meta_keys:
38
+ raise CompileError(
39
+ f"Unknown keys in '_meta': {', '.join(sorted(unknown_meta_keys))}"
40
+ )
41
+
42
+ raw_stages = meta.get("stages")
43
+ if (
44
+ not isinstance(raw_stages, list)
45
+ or not raw_stages
46
+ or not all(isinstance(s, str) and s.strip() for s in raw_stages)
47
+ ):
48
+ raise CompileError("'_meta.stages' must be a non-empty list of stage names.")
49
+
50
+ if len(set(raw_stages)) != len(raw_stages):
51
+ raise CompileError("'_meta.stages' contains duplicate stage names.")
52
+
53
+ stages = set(raw_stages)
54
+ consts: dict[str, list[str]] = {}
55
+
56
+ if "consts" in meta and meta["consts"] is not None:
57
+ raw_consts = meta["consts"]
58
+ if not isinstance(raw_consts, dict):
59
+ raise CompileError("'_meta.consts' must be a mapping if present.")
60
+
61
+ for name, items in raw_consts.items():
62
+ if not isinstance(name, str) or not name.strip():
63
+ raise CompileError(
64
+ "Constant names in '_meta.consts' must be non-empty strings."
65
+ )
66
+ if (
67
+ not isinstance(items, list)
68
+ or not items
69
+ or not all(isinstance(item, str) and item.strip() for item in items)
70
+ ):
71
+ raise CompileError(
72
+ f"'_meta.consts.{name}' must be a non-empty flat list of non-empty strings."
73
+ )
74
+ consts[name] = list(items)
75
+ return stages, consts
76
+
77
+
78
+ def _validate_tree(
79
+ node: Any,
80
+ stages: set[str],
81
+ consts: dict[str, list[str]],
82
+ used_consts: set[str],
83
+ path: str = "root",
84
+ in_stage: bool = False,
85
+ ) -> None:
86
+ if isinstance(node, dict):
87
+ keys = set(node.keys())
88
+ matched_stages = keys & stages
89
+
90
+ if matched_stages:
91
+ if in_stage:
92
+ raise CompileError(
93
+ f"Nested stage switch at '{path}': path is already inside a stage branch."
94
+ )
95
+ non_stage_keys = keys - stages
96
+ if non_stage_keys:
97
+ raise CompileError(
98
+ f"Stage collision at '{path}': reserved stage key(s) "
99
+ f"{sorted(matched_stages)} mixed with regular key(s) {sorted(non_stage_keys)}."
100
+ )
101
+ for stage_key, val in node.items():
102
+ child_path = f"{path}.{stage_key}"
103
+ if _is_empty(val):
104
+ raise CompileError(
105
+ f"Empty value at '{child_path}': stage entries cannot be null or empty."
106
+ )
107
+ _validate_tree(
108
+ val, stages, consts, used_consts, child_path, in_stage=True
109
+ )
110
+ else:
111
+ for k, val in node.items():
112
+ _validate_tree(
113
+ val, stages, consts, used_consts, f"{path}.{k}", in_stage=in_stage
114
+ )
115
+
116
+ elif isinstance(node, list):
117
+ for idx, item in enumerate(node):
118
+ _validate_tree(
119
+ item, stages, consts, used_consts, f"{path}[{idx}]", in_stage=in_stage
120
+ )
121
+
122
+ elif isinstance(node, str):
123
+ exact = EXACT_INTERP_RE.match(node.strip())
124
+ if exact:
125
+ var_name = exact.group(1)
126
+ if var_name in consts:
127
+ if node != exact.group(0):
128
+ raise CompileError(
129
+ f"Invalid whitespace around constant '${{{var_name}}}' at '{path}'."
130
+ )
131
+ used_consts.add(var_name)
132
+ else:
133
+ for match in INTERP_RE.finditer(node):
134
+ var_name = match.group(1)
135
+ if var_name in consts:
136
+ raise CompileError(
137
+ f"Invalid constant interpolation at '{path}': '${{{var_name}}}' is a list "
138
+ f"and must occupy the entire scalar value, not be embedded in a string."
139
+ )
140
+
141
+
142
+ class _OmitNode:
143
+ pass
144
+
145
+
146
+ OMIT = _OmitNode()
147
+
148
+
149
+ def _resolve_node(
150
+ node: Any,
151
+ target_stage: str,
152
+ stages: set[str],
153
+ consts: dict[str, list[str]],
154
+ ) -> Any:
155
+ if isinstance(node, dict):
156
+ keys = set(node.keys())
157
+ if keys & stages:
158
+ if target_stage not in node:
159
+ return OMIT
160
+ return _resolve_node(node[target_stage], target_stage, stages, consts)
161
+
162
+ resolved_dict = CommentedMap()
163
+ if isinstance(node, CommentedMap) and node.ca.comment:
164
+ resolved_dict.ca.comment = copy.deepcopy(node.ca.comment)
165
+
166
+ for k, v in node.items():
167
+ resolved_val = _resolve_node(v, target_stage, stages, consts)
168
+ if resolved_val is not OMIT:
169
+ resolved_dict[k] = resolved_val
170
+ if isinstance(node, CommentedMap) and k in node.ca.items:
171
+ resolved_dict.ca.items[k] = copy.deepcopy(node.ca.items[k])
172
+
173
+ if not resolved_dict and len(node) > 0:
174
+ return OMIT
175
+
176
+ return resolved_dict
177
+
178
+ if isinstance(node, list):
179
+ resolved_list = CommentedSeq()
180
+ if isinstance(node, CommentedSeq) and node.ca.comment:
181
+ resolved_list.ca.comment = copy.deepcopy(node.ca.comment)
182
+
183
+ for idx, item in enumerate(node):
184
+ resolved_item = _resolve_node(item, target_stage, stages, consts)
185
+ if resolved_item is not OMIT:
186
+ new_idx = len(resolved_list)
187
+ resolved_list.append(resolved_item)
188
+ if isinstance(node, CommentedSeq) and idx in node.ca.items:
189
+ resolved_list.ca.items[new_idx] = copy.deepcopy(node.ca.items[idx])
190
+ return resolved_list
191
+
192
+ if isinstance(node, str):
193
+ exact = EXACT_INTERP_RE.match(node)
194
+ if exact and exact.group(1) in consts:
195
+ return copy.deepcopy(consts[exact.group(1)])
196
+
197
+ return copy.deepcopy(node)
198
+
199
+
200
+ def compile_blueprint(source_yaml: str, target_stage: str) -> str:
201
+ yaml = YAML(typ="rt")
202
+ yaml.preserve_quotes = True
203
+ yaml.indent(mapping=2, sequence=4, offset=2)
204
+ yaml.width = 4096
205
+
206
+ data = yaml.load(source_yaml)
207
+ stages, consts = _parse_meta(data)
208
+
209
+ if target_stage not in stages:
210
+ raise CompileError(
211
+ f"Unknown stage '{target_stage}'. Allowed stages: {', '.join(sorted(stages))}"
212
+ )
213
+
214
+ body = {k: v for k, v in data.items() if k != "_meta"}
215
+ used_consts: set[str] = set()
216
+ _validate_tree(body, stages, consts, used_consts)
217
+
218
+ unused = set(consts.keys()) - used_consts
219
+ if unused:
220
+ raise CompileError(
221
+ f"Unused constant(s) defined in '_meta.consts': {', '.join(sorted(unused))}"
222
+ )
223
+
224
+ compiled = _resolve_node(body, target_stage, stages, consts)
225
+ if compiled is OMIT or not compiled:
226
+ raise CompileError(
227
+ f"Compilation for stage '{target_stage}' produced an empty document."
228
+ )
229
+
230
+ header = (
231
+ f"# Auto-generated configuration for stage: {target_stage}\n"
232
+ f"# DO NOT EDIT DIRECTLY. Manage via stage.yaml\n\n"
233
+ )
234
+ stream = StringIO()
235
+ yaml.dump(compiled, stream)
236
+ return header + stream.getvalue()
stageyy/py.typed ADDED
File without changes
@@ -0,0 +1,11 @@
1
+ Metadata-Version: 2.3
2
+ Name: stageyy
3
+ Version: 0.1.0
4
+ Summary: Add your description here
5
+ Author: Trevor Wong
6
+ Author-email: Trevor Wong <stephen.trevor.wong@outlook.com>
7
+ Requires-Dist: ruamel-yaml>=0.19.1
8
+ Requires-Dist: watchfiles>=1.3.0
9
+ Requires-Python: >=3.13
10
+ Description-Content-Type: text/markdown
11
+
@@ -0,0 +1,8 @@
1
+ stageyy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
2
+ stageyy/cli.py,sha256=jpOwLoPyPrldQYH1pRMuZ7oOoq3g0X1XtLLqJXZuDh4,8301
3
+ stageyy/compiler.py,sha256=XstLbzKcq2e0GdbCfRtJFdJPw7YZXL8UBjsHsSqNGqk,8104
4
+ stageyy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
5
+ stageyy-0.1.0.dist-info/WHEEL,sha256=3OmCxFA0ffBIsX4x0o8CdfSvZAOvO3mzEG8U_z5TvV4,80
6
+ stageyy-0.1.0.dist-info/entry_points.txt,sha256=jQhpYxOMl6Ic4rrGc9VxTIb6rdEokTjZo7ahfMPiMC0,72
7
+ stageyy-0.1.0.dist-info/METADATA,sha256=0zefWFc7XWpqxQh9TPYzpalGDCPj_gfzUZNmGdcRSnE,299
8
+ stageyy-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.13.8
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,4 @@
1
+ [console_scripts]
2
+ stagey = stageyy.cli:main
3
+ stageyy = stageyy.cli:main
4
+