seanerstack 0.1.3__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.
seanerstack/cli.py ADDED
@@ -0,0 +1,397 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ from pathlib import Path
6
+ import subprocess
7
+ import sys
8
+
9
+ from .bootstrap import DEFAULT_LANGUAGES, DEFAULT_PROBE, DEFAULT_PROBE_TIMEOUT, bootstrap
10
+ from .buildcache import buildcaches, check_buildcaches, configure_buildcaches
11
+ from .config import Config, load_config
12
+ from .paths import environments_path, repository_path, share_path
13
+ from .secrets import SecretStore
14
+ from .isolation import (
15
+ activation_script, deactivation_script, layout, prepare_isolation,
16
+ resolve_real_spack, resolve_state_dir, spack_command, spack_env,
17
+ )
18
+ from .sync import package_paths, sync_many
19
+ from .validate import validate
20
+
21
+
22
+ def _add_secret_options(parser: argparse.ArgumentParser) -> None:
23
+ parser.add_argument(
24
+ "--config-file",
25
+ type=Path,
26
+ help="Seanerstack config.toml (default: installed share/seanerstack/config.toml)",
27
+ )
28
+ parser.add_argument(
29
+ "--secrets-file",
30
+ type=Path,
31
+ help="keyloom-encrypted file containing credentials referenced by config.toml",
32
+ )
33
+ source = parser.add_mutually_exclusive_group()
34
+ source.add_argument(
35
+ "--secrets-password-file",
36
+ type=Path,
37
+ help="read the vault password from FILE instead of prompting",
38
+ )
39
+ source.add_argument(
40
+ "--secrets-password-stdin",
41
+ action="store_true",
42
+ help="read the vault password from stdin instead of prompting",
43
+ )
44
+
45
+
46
+ def build_parser() -> argparse.ArgumentParser:
47
+ parser = argparse.ArgumentParser(
48
+ prog="seanerstack",
49
+ description="Maintain and use the curated SEANERGYS Spack stack.",
50
+ )
51
+ _add_secret_options(parser)
52
+ parser.add_argument("--state-dir", type=Path, help="private Seanerstack state directory (or SEANERSTACK_STATE_DIR)")
53
+ parser.add_argument("--spack-executable", type=Path, help="real Spack executable to use for the isolated session")
54
+ subparsers = parser.add_subparsers(dest="command", required=True)
55
+
56
+ package_parser = subparsers.add_parser("package", help="Maintain curated Spack packages.")
57
+ package_sub = package_parser.add_subparsers(dest="package_command", required=True)
58
+ update_parser = package_sub.add_parser(
59
+ "update",
60
+ help="Update Spack recipe versions from upstream Git refs.",
61
+ description=(
62
+ "Read each native package.py recipe, infer its release-tag convention "
63
+ "from existing version(..., tag=...) directives, and add missing upstream releases."
64
+ ),
65
+ )
66
+ update_parser.add_argument("package", nargs="?", help="package to update")
67
+ update_parser.add_argument("--all", action="store_true", help="update every Seanerstack package")
68
+ update_parser.add_argument("--check", action="store_true", help="report drift without changing files; return non-zero on drift")
69
+ update_parser.add_argument("--dry-run", action="store_true", help="show what would change without changing files")
70
+
71
+ toolchain_parser = subparsers.add_parser("toolchain", help="Prepare the SEANERGYS build toolchain.")
72
+ toolchain_sub = toolchain_parser.add_subparsers(dest="toolchain_command", required=True)
73
+ bootstrap_parser = toolchain_sub.add_parser(
74
+ "bootstrap",
75
+ help="Bootstrap a Spack-installed production compiler.",
76
+ description=(
77
+ "Install COMPILER through Spack if needed, then configure native Spack "
78
+ "language-provider requirements so subsequent environment concretization uses it."
79
+ ),
80
+ )
81
+ bootstrap_parser.add_argument("compiler", help="Spack compiler spec, for example gcc@15")
82
+ bootstrap_parser.add_argument(
83
+ "--language",
84
+ action="append",
85
+ choices=("c", "cxx", "fortran"),
86
+ help="language provider to configure; repeat as needed (default: c, cxx, fortran)",
87
+ )
88
+ bootstrap_parser.add_argument("--probe", default=DEFAULT_PROBE, help=f"spec used to probe concretization (default: {DEFAULT_PROBE})")
89
+ bootstrap_parser.add_argument("--probe-timeout", type=float, default=DEFAULT_PROBE_TIMEOUT, help=f"seconds to allow the probe before giving up (default: {DEFAULT_PROBE_TIMEOUT:g}); 0 waits indefinitely")
90
+ bootstrap_parser.add_argument("--force", action="store_true", help="ask Spack to install the compiler even when it is already installed")
91
+ bootstrap_parser.add_argument("--dry-run", action="store_true", help="show the intended operation without changing Spack configuration")
92
+
93
+ validate_parser = subparsers.add_parser(
94
+ "validate",
95
+ help="Validate recipes, environments, resources, and optional online/Spack state.",
96
+ )
97
+ validate_parser.add_argument("--online", action="store_true", help="also compare recipe versions with upstream Git refs")
98
+ validate_parser.add_argument("--spack", action="store_true", dest="with_spack", help="also concretize copies of all environments with Spack")
99
+ validate_parser.add_argument("--compiler", help="verify that this compiler is required for the selected languages")
100
+ validate_parser.add_argument(
101
+ "--language",
102
+ action="append",
103
+ choices=("c", "cxx", "fortran"),
104
+ help="language requirement to validate; repeat as needed (default: c, cxx, fortran)",
105
+ )
106
+
107
+ paths_parser = subparsers.add_parser("paths", help="Print installed Seanerstack paths.")
108
+ paths_sub = paths_parser.add_subparsers(dest="paths_command", required=True)
109
+ paths_sub.add_parser("share", help="Print the installed Seanerstack share directory.")
110
+ paths_sub.add_parser("repo", help="Print the native Seanerstack Spack repository path.")
111
+ env_parser = paths_sub.add_parser("env", help="Print the path of a shipped Spack environment.")
112
+ selector = env_parser.add_mutually_exclusive_group(required=True)
113
+ selector.add_argument("--package", help="select the unique environment whose root specs contain PACKAGE")
114
+ selector.add_argument("--environment", help="select an environment by directory name")
115
+
116
+ cache_parser = subparsers.add_parser("buildcache", help="Configure and verify Spack binary build caches.")
117
+ cache_sub = cache_parser.add_subparsers(dest="buildcache_command", required=True)
118
+ cache_sub.add_parser("configure", help="Install configured build-cache mirrors into the isolated Spack configuration.")
119
+ cache_sub.add_parser("check", help="Check access to configured build caches using session or vault credentials.")
120
+
121
+ init_parser = subparsers.add_parser(
122
+ "init",
123
+ help="Bootstrap the compiler, configure build-cache/OCI registry access, and validate, in one step.",
124
+ description=(
125
+ "Prepare a complete Seanerstack setup in one command: bootstrap COMPILER "
126
+ "through Spack, configure the build caches declared in config.toml "
127
+ "(including OCI registry access, using --secrets-file), and validate "
128
+ "the result."
129
+ ),
130
+ )
131
+ init_parser.add_argument("compiler", help="Spack compiler spec, for example gcc@15")
132
+ init_parser.add_argument(
133
+ "--language",
134
+ action="append",
135
+ choices=("c", "cxx", "fortran"),
136
+ help="language provider to configure; repeat as needed (default: c, cxx, fortran)",
137
+ )
138
+ init_parser.add_argument("--probe", default=DEFAULT_PROBE, help=f"spec used to probe concretization (default: {DEFAULT_PROBE})")
139
+ init_parser.add_argument("--probe-timeout", type=float, default=DEFAULT_PROBE_TIMEOUT, help=f"seconds to allow the probe before giving up (default: {DEFAULT_PROBE_TIMEOUT:g}); 0 waits indefinitely")
140
+ init_parser.add_argument("--force", action="store_true", help="ask Spack to install the compiler even when it is already installed")
141
+ init_parser.add_argument("--skip-buildcache-check", action="store_true", help="configure build-cache mirrors without verifying access")
142
+ init_parser.add_argument("--skip-validate", action="store_true", help="skip the final validation pass")
143
+
144
+ subparsers.add_parser("activate", help="Emit shell code that activates an isolated Seanerstack Spack session.")
145
+ subparsers.add_parser("deactivate", help="Emit shell code that restores the shell state saved by activation.")
146
+
147
+ return parser
148
+
149
+
150
+ def _runtime(args: argparse.Namespace) -> tuple[Config, SecretStore]:
151
+ config = load_config(args.config_file)
152
+ secrets = SecretStore(
153
+ args.secrets_file,
154
+ password_file=args.secrets_password_file,
155
+ password_stdin=args.secrets_password_stdin,
156
+ )
157
+ return config, secrets
158
+
159
+
160
+ def _run_package_update(args: argparse.Namespace) -> int:
161
+ config, secrets = _runtime(args)
162
+ paths = package_paths()
163
+ if args.all:
164
+ packages = list(paths)
165
+ elif args.package:
166
+ packages = [args.package]
167
+ else:
168
+ raise ValueError("provide PACKAGE or --all")
169
+
170
+ results = sync_many(
171
+ packages,
172
+ check=args.check,
173
+ dry_run=args.dry_run,
174
+ config=config,
175
+ secrets=secrets,
176
+ )
177
+ drift = False
178
+ for result in results:
179
+ if not result.changed:
180
+ print(f"{result.package}: up to date")
181
+ continue
182
+ drift = True
183
+ changes = [*(f"version {version}" for version in result.missing_versions)]
184
+ changes.extend(f"missing upstream branch {branch}" for branch in result.missing_branches)
185
+ verb = "would add/report" if (args.check or args.dry_run) else "added/reported"
186
+ print(f"{result.package}: {verb} " + ", ".join(changes))
187
+ return 1 if args.check and drift else 0
188
+
189
+
190
+
191
+ def _spack_runtime(args: argparse.Namespace):
192
+ state_dir = resolve_state_dir(args.state_dir)
193
+ real_spack = resolve_real_spack(args.spack_executable)
194
+ x = prepare_isolation(state_dir, real_spack)
195
+ env = dict(__import__("os").environ)
196
+ env.update(spack_env(x))
197
+ return x, real_spack, spack_command(x, real_spack), env
198
+
199
+ def _run_bootstrap(args: argparse.Namespace) -> int:
200
+ languages = tuple(args.language) if args.language else DEFAULT_LANGUAGES
201
+ _, _, command, env = _spack_runtime(args)
202
+ result = bootstrap(
203
+ args.compiler,
204
+ languages=languages,
205
+ probe=args.probe,
206
+ command=command,
207
+ env=env,
208
+ force=args.force,
209
+ dry_run=args.dry_run,
210
+ probe_timeout=args.probe_timeout or None,
211
+ )
212
+ if args.dry_run:
213
+ print(f"would bootstrap {result.compiler}")
214
+ print(f"would require it for: {', '.join(result.languages)}")
215
+ return 0
216
+ print(f"compiler: {result.compiler}")
217
+ print(f"registered as external: {'yes' if result.registered else 'no'}")
218
+ print(f"languages: {', '.join(result.languages)}")
219
+ print(f"compiler probe ({result.probe}): {'ok' if result.probe_ok else 'warning: compiler name not visible in probe output'}")
220
+ return 0 if result.probe_ok else 1
221
+
222
+
223
+ def _run_init(args: argparse.Namespace) -> int:
224
+ config, secrets = _runtime(args)
225
+ languages = tuple(args.language) if args.language else DEFAULT_LANGUAGES
226
+ _, _, command, env = _spack_runtime(args)
227
+
228
+ result = bootstrap(
229
+ args.compiler,
230
+ languages=languages,
231
+ probe=args.probe,
232
+ command=command,
233
+ env=env,
234
+ force=args.force,
235
+ probe_timeout=args.probe_timeout or None,
236
+ )
237
+ print(f"compiler: {result.compiler}")
238
+ print(f"registered as external: {'yes' if result.registered else 'no'}")
239
+ print(f"languages: {', '.join(result.languages)}")
240
+ print(f"compiler probe ({result.probe}): {'ok' if result.probe_ok else 'warning: compiler name not visible in probe output'}")
241
+ failed = not result.probe_ok
242
+
243
+ configure_buildcaches(config, command=command, env=env)
244
+ print(f"build caches: configured {len(buildcaches(config))} resource(s)")
245
+
246
+ if not args.skip_buildcache_check:
247
+ for name, ok, message in check_buildcaches(config, secrets, command=command, base_env=env):
248
+ print(f"[{'OK' if ok else 'ERROR'}] buildcache:{name}: {message or 'accessible'}")
249
+ failed |= not ok
250
+
251
+ if not args.skip_validate:
252
+ findings = validate(
253
+ with_spack=True,
254
+ compiler=args.compiler,
255
+ languages=languages,
256
+ spack_command=command,
257
+ spack_env=env,
258
+ config=config,
259
+ secrets=secrets,
260
+ )
261
+ for finding in findings:
262
+ marker = {"ok": "OK", "warning": "WARN", "error": "ERROR"}[finding.level]
263
+ print(f"[{marker}] {finding.subject}: {finding.message}")
264
+ failed |= finding.level == "error"
265
+
266
+ if not failed:
267
+ print()
268
+ print("Setup complete. Activate with:")
269
+ print(' eval "$(seanerstack activate)"')
270
+ return 1 if failed else 0
271
+
272
+
273
+ def _environment_packages(path) -> set[str]:
274
+ import re
275
+ import yaml
276
+
277
+ data = yaml.safe_load((path / "spack.yaml").read_text(encoding="utf-8")) or {}
278
+ specs = data.get("spack", {}).get("specs", [])
279
+ packages: set[str] = set()
280
+ for spec in specs:
281
+ if not isinstance(spec, str):
282
+ continue
283
+ match = re.match(r"\s*([A-Za-z0-9_.-]+)", spec)
284
+ if match:
285
+ packages.add(match.group(1).split(".")[-1].replace("_", "-"))
286
+ return packages
287
+
288
+
289
+ def _run_envpath(args: argparse.Namespace) -> int:
290
+ root = environments_path()
291
+ if args.environment:
292
+ path = root / args.environment
293
+ if not (path / "spack.yaml").is_file():
294
+ raise ValueError(f"unknown Seanerstack environment: {args.environment}")
295
+ print(path)
296
+ return 0
297
+
298
+ package = args.package.replace("_", "-")
299
+ matches = [
300
+ path
301
+ for path in sorted(p for p in root.iterdir() if p.is_dir() and (p / "spack.yaml").is_file())
302
+ if package in _environment_packages(path)
303
+ ]
304
+ if not matches:
305
+ raise ValueError(f"no Seanerstack environment contains root package {args.package!r}")
306
+ if len(matches) > 1:
307
+ names = ", ".join(path.name for path in matches)
308
+ raise ValueError(f"multiple Seanerstack environments contain {args.package!r}: {names}; use --environment")
309
+ print(matches[0])
310
+ return 0
311
+
312
+
313
+ def _run_validate(args: argparse.Namespace) -> int:
314
+ config, secrets = _runtime(args)
315
+ languages = tuple(args.language) if args.language else DEFAULT_LANGUAGES
316
+ command = env = None
317
+ if args.with_spack or args.compiler:
318
+ _, _, command, env = _spack_runtime(args)
319
+ findings = validate(
320
+ online=args.online,
321
+ with_spack=args.with_spack,
322
+ compiler=args.compiler,
323
+ languages=languages,
324
+ spack_command=command,
325
+ spack_env=env,
326
+ config=config,
327
+ secrets=secrets,
328
+ )
329
+ failed = False
330
+ for finding in findings:
331
+ marker = {"ok": "OK", "warning": "WARN", "error": "ERROR"}[finding.level]
332
+ print(f"[{marker}] {finding.subject}: {finding.message}")
333
+ failed |= finding.level == "error"
334
+ return 1 if failed else 0
335
+
336
+
337
+ def _run_buildcache(args: argparse.Namespace) -> int:
338
+ config, secrets = _runtime(args)
339
+ if args.buildcache_command == "configure":
340
+ _, _, command, env = _spack_runtime(args)
341
+ configure_buildcaches(config, command=command, env=env)
342
+ return 0
343
+ if args.buildcache_command == "check":
344
+ _, _, command, env = _spack_runtime(args)
345
+ failed = False
346
+ for name, ok, message in check_buildcaches(config, secrets, command=command, base_env=env):
347
+ print(f"[{'OK' if ok else 'ERROR'}] buildcache:{name}: {message or 'accessible'}")
348
+ failed |= not ok
349
+ return 1 if failed else 0
350
+ raise ValueError(f"unknown buildcache command: {args.buildcache_command}")
351
+
352
+
353
+ def main(argv: list[str] | None = None) -> None:
354
+ parser = build_parser()
355
+ args = parser.parse_args(argv)
356
+ try:
357
+ if args.command == "package" and args.package_command == "update":
358
+ code = _run_package_update(args)
359
+ elif args.command == "toolchain" and args.toolchain_command == "bootstrap":
360
+ code = _run_bootstrap(args)
361
+ elif args.command == "validate":
362
+ code = _run_validate(args)
363
+ elif args.command == "paths":
364
+ if args.paths_command == "share":
365
+ print(share_path())
366
+ code = 0
367
+ elif args.paths_command == "repo":
368
+ print(repository_path())
369
+ code = 0
370
+ elif args.paths_command == "env":
371
+ code = _run_envpath(args)
372
+ else:
373
+ raise ValueError(f"unknown paths command: {args.paths_command}")
374
+ elif args.command == "buildcache":
375
+ code = _run_buildcache(args)
376
+ elif args.command == "init":
377
+ code = _run_init(args)
378
+ elif args.command == "activate":
379
+ config, secrets = _runtime(args)
380
+ state_dir = resolve_state_dir(args.state_dir)
381
+ real_spack = resolve_real_spack(args.spack_executable)
382
+ print(activation_script(state_dir=state_dir, real_spack=real_spack, config=config, secrets=secrets), end="")
383
+ code = 0
384
+ elif args.command == "deactivate":
385
+ print(deactivation_script(), end="")
386
+ code = 0
387
+ else:
388
+ parser.error(f"unknown command: {args.command}")
389
+ return
390
+ except (RuntimeError, ValueError, OSError, subprocess.CalledProcessError) as error:
391
+ print(f"seanerstack: error: {error}", file=sys.stderr)
392
+ code = 2
393
+ raise SystemExit(code)
394
+
395
+
396
+ if __name__ == "__main__":
397
+ main()
seanerstack/config.py ADDED
@@ -0,0 +1,93 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ from __future__ import annotations
3
+
4
+ from dataclasses import dataclass
5
+ from pathlib import Path
6
+ import re
7
+ import tomllib
8
+
9
+ from .paths import share_path
10
+
11
+
12
+ @dataclass(frozen=True)
13
+ class Resource:
14
+ name: str
15
+ kind: str
16
+ url: str
17
+ credentials: str | None = None
18
+ endpoint_url: str | None = None
19
+ autopush: bool = False
20
+ signed: bool = True
21
+
22
+ @property
23
+ def env_prefix(self) -> str:
24
+ normalized = re.sub(r"[^A-Za-z0-9]+", "_", self.name).strip("_").upper()
25
+ return f"SEANERSTACK_RESOURCE_{normalized}"
26
+
27
+ @property
28
+ def oci(self) -> bool:
29
+ return self.url.startswith(("oci://", "oci+http://"))
30
+
31
+ @property
32
+ def filesystem(self) -> bool:
33
+ return self.url.startswith("file://")
34
+
35
+ @property
36
+ def credential_variables(self) -> tuple[str, str]:
37
+ """Variables Spack reads the user name (or key id) and secret from."""
38
+ if self.oci:
39
+ return (f"{self.env_prefix}_USERNAME", f"{self.env_prefix}_PASSWORD")
40
+ return (f"{self.env_prefix}_ACCESS_KEY_ID", f"{self.env_prefix}_SECRET_ACCESS_KEY")
41
+
42
+
43
+ @dataclass(frozen=True)
44
+ class Config:
45
+ path: Path
46
+ resources: dict[str, Resource]
47
+
48
+ def resource(self, name: str) -> Resource:
49
+ try:
50
+ return self.resources[name]
51
+ except KeyError as error:
52
+ raise ValueError(f"unknown Seanerstack resource: {name}") from error
53
+
54
+
55
+ def default_config_path() -> Path:
56
+ return share_path() / "config.toml"
57
+
58
+
59
+ def load_config(path: Path | None = None) -> Config:
60
+ path = path or default_config_path()
61
+ if not path.is_file():
62
+ raise ValueError(f"Seanerstack config does not exist: {path}")
63
+ data = tomllib.loads(path.read_text(encoding="utf-8"))
64
+ raw_resources = data.get("resources", {})
65
+ if not isinstance(raw_resources, dict):
66
+ raise ValueError(f"{path}: [resources] must be a table")
67
+
68
+ resources: dict[str, Resource] = {}
69
+ for name, raw in raw_resources.items():
70
+ if not isinstance(raw, dict):
71
+ raise ValueError(f"{path}: resources.{name} must be a table")
72
+ kind = raw.get("kind")
73
+ url = raw.get("url")
74
+ if not isinstance(kind, str) or not isinstance(url, str):
75
+ raise ValueError(f"{path}: resources.{name} requires string kind and url")
76
+ resource = Resource(
77
+ name=name,
78
+ kind=kind,
79
+ url=url,
80
+ credentials=raw.get("credentials") if isinstance(raw.get("credentials"), str) else None,
81
+ endpoint_url=raw.get("endpoint_url") if isinstance(raw.get("endpoint_url"), str) else None,
82
+ autopush=bool(raw.get("autopush", False)),
83
+ # A filesystem cache is local or project-private, so it defaults to unsigned.
84
+ signed=bool(raw.get("signed", not url.startswith("file://"))),
85
+ )
86
+ # Spack cannot sign OCI build caches; it warns and pushes unsigned anyway.
87
+ if resource.kind == "spack-buildcache" and resource.oci and resource.signed:
88
+ raise ValueError(f"{path}: resources.{name}: OCI build caches cannot be signed; set signed = false")
89
+ # File permissions are the access control of a filesystem cache.
90
+ if resource.kind == "spack-buildcache" and resource.filesystem and resource.credentials:
91
+ raise ValueError(f"{path}: resources.{name}: filesystem build caches take no credentials")
92
+ resources[name] = resource
93
+ return Config(path=path, resources=resources)
seanerstack/docsgen.py ADDED
@@ -0,0 +1,146 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+
6
+ import yaml
7
+
8
+ from .cli import build_parser
9
+ from .paths import environments_path, share_path
10
+ from .recipe import parse_recipe
11
+ from .sync import package_paths
12
+
13
+
14
+ def _write(path: str, content: str) -> None:
15
+ import mkdocs_gen_files
16
+
17
+ with mkdocs_gen_files.open(path, "w") as handle:
18
+ handle.write(content.rstrip() + "\n")
19
+
20
+
21
+ def _subparsers(parser: argparse.ArgumentParser) -> dict[str, argparse.ArgumentParser]:
22
+ for action in parser._actions:
23
+ if isinstance(action, argparse._SubParsersAction):
24
+ return dict(action.choices)
25
+ return {}
26
+
27
+
28
+ def _cli_pages(command: str, parser: argparse.ArgumentParser):
29
+ yield command, parser
30
+ for name, child in _subparsers(parser).items():
31
+ yield from _cli_pages(f"{command} {name}", child)
32
+
33
+
34
+ def generate_cli() -> None:
35
+ parser = build_parser()
36
+ pages = list(_cli_pages("seanerstack", parser))
37
+ links: list[str] = []
38
+ for command, command_parser in pages:
39
+ slug = command.replace(" ", "-")
40
+ links.append(f"- [`{command}`]({slug}.md)")
41
+ help_text = command_parser.format_help().rstrip()
42
+ content = f"# `{command}`\n\n{command_parser.description or ''}\n\n```text\n{help_text}\n```\n"
43
+ _write(f"reference/cli/{slug}.md", content)
44
+ _write("reference/cli/index.md", "# Command line reference\n\n" + "\n".join(links))
45
+
46
+
47
+ def _directive_table(directives, name: str) -> str:
48
+ selected = [directive for directive in directives if directive.name == name]
49
+ if not selected:
50
+ return "_None._"
51
+ rows = ["| Declaration | Recipe comment |", "| --- | --- |"]
52
+ for directive in selected:
53
+ declaration = " ".join(directive.source.strip().split()).replace("|", "\\|")
54
+ comment = (directive.comment or "").replace("|", "\\|")
55
+ rows.append(f"| `{declaration}` | {comment} |")
56
+ return "\n".join(rows)
57
+
58
+
59
+ def generate_packages() -> None:
60
+ root = share_path()
61
+ links: list[str] = []
62
+ for name, path in package_paths().items():
63
+ recipe = parse_recipe(path)
64
+ links.append(f"- [{name}]({name}.md)")
65
+ attrs = []
66
+ for key in ("homepage", "git", "url", "pypi", "seanerstack_resource"):
67
+ if key in recipe.attributes:
68
+ attrs.append(f"- **{key}:** `{recipe.attributes[key]}`")
69
+ content = f"""# {name}
70
+
71
+ {recipe.docstring or '_No package description is present in the recipe._'}
72
+
73
+ ## Source
74
+
75
+ {chr(10).join(attrs) if attrs else '_No source attributes found._'}
76
+
77
+ Recipe: `share/seanerstack/{path.relative_to(root)}`
78
+
79
+ ## Versions
80
+
81
+ {_directive_table(recipe.directives, 'version')}
82
+
83
+ ## Variants
84
+
85
+ {_directive_table(recipe.directives, 'variant')}
86
+
87
+ ## Dependencies
88
+
89
+ {_directive_table(recipe.directives, 'depends_on')}
90
+
91
+ ## Conflicts
92
+
93
+ {_directive_table(recipe.directives, 'conflicts')}
94
+
95
+ ## Provides
96
+
97
+ {_directive_table(recipe.directives, 'provides')}
98
+ """
99
+ _write(f"reference/packages/{name}.md", content)
100
+ _write("reference/packages/index.md", "# Package reference\n\nGenerated directly from the native Spack recipes.\n\n" + "\n".join(links))
101
+
102
+
103
+ def _format_yaml(value) -> str:
104
+ return "```yaml\n" + yaml.safe_dump(value, sort_keys=False).rstrip() + "\n```"
105
+
106
+
107
+ def generate_environments() -> None:
108
+ root = share_path()
109
+ envs = environments_path()
110
+ links: list[str] = []
111
+ for directory in sorted(path for path in envs.iterdir() if path.is_dir()):
112
+ manifest = directory / "spack.yaml"
113
+ if not manifest.is_file():
114
+ continue
115
+ raw = manifest.read_text(encoding="utf-8")
116
+ data = yaml.safe_load(raw) or {}
117
+ spack = data.get("spack", {})
118
+ links.append(f"- [{directory.name}]({directory.name}.md)")
119
+ specs = spack.get("specs", [])
120
+ develop = spack.get("develop")
121
+ content = f"""# {directory.name}
122
+
123
+ Manifest: `share/seanerstack/{manifest.relative_to(root)}`
124
+
125
+ ## Root specs
126
+
127
+ {_format_yaml(specs)}
128
+
129
+ ## Develop bindings
130
+
131
+ {_format_yaml(develop) if develop else '_No checkout path is committed. Use `spack develop` to bind local sources._'}
132
+
133
+ ## Complete manifest
134
+
135
+ ```yaml
136
+ {raw.rstrip()}
137
+ ```
138
+ """
139
+ _write(f"reference/environments/{directory.name}.md", content)
140
+ _write("reference/environments/index.md", "# Environment reference\n\nGenerated directly from native `spack.yaml` manifests.\n\n" + "\n".join(links))
141
+
142
+
143
+ def main() -> None:
144
+ generate_cli()
145
+ generate_packages()
146
+ generate_environments()