scalio-catalog 0.1.0__tar.gz

scalio_catalog-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: scalio-catalog
+Version: 0.1.0
+Summary: Scalio Blueprint governance catalog (scalio.catalog/v2): check, effective desired state, drift, signed packs
+License: Proprietary
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+
+# scalio-catalog
+
+Shared code for the Scalio Blueprint governance catalog: one desired state per tenant, used by Foundry (roll
+out), Citadel (keep, drift) and Rosetta (document). Concept and decisions BP1-BP12:
+https://claude.ai/artifact/8PYfvHPm17KsooerLU95Ar (scalio-docs `concepts/governance-catalog.md`, ADR 0027).
+Format contract: scalio-docs `interfaces/catalog-format.md`.
+
+Nothing in this package is secret. The catalog content lives in the private repo `scalio_blueprint`; the signing
+seed stays in 1Password.
+
+## Documents
+
+| Kind | What | Owner |
+| --- | --- | --- |
+| `ResourceType` | Something in a tenant (name as in Microsoft365DSC/UTCM, e.g. `AADConditionalAccessPolicy`): properties, read/write endpoint, permission | Scalio |
+| `Control` | One security statement: match, desired values, parameters, severity, texts DE/EN, frameworks | Scalio, MSP, customer |
+| `Baseline` | Versioned bundle of controls with default values | Scalio, MSP |
+| `Assignment` | Tenant -> baseline@version, mode, channel, values, exceptions, own controls | customer |
+| `Pack` | Header of a signed package | Scalio, MSP |
+
+References: `id` (highest), `id@1.2.3` (exact), `id@^1.2` (same major, at least 1.2). Assignments name an exact
+version.
+
+## Use in an app
+
+```python
+from scalio_catalog import Catalog, compare, effective, plan_upgrade, summary, verify
+
+catalog = verify(package_bytes, TRUSTED_CATALOG_KEYS)        # signed pack from Compass or the image
+eff = effective(catalog, assignment)                         # baseline + customer layer, master untouched
+results = compare(eff, {c.id: read_resource(c) for c in eff.controls})   # app reads the tenant
+print(summary(results))                                      # {"counts": ..., "score": 92}
+plan = plan_upgrade(catalog, assignment, "scalio.kmu-standard@1.5.0")    # three-way, conflicts listed
+```
+
+`compare` statuses: `ok`, `drift`, `missing`, `excepted` (all deviations covered by an active exception),
+`not_read`, `removed` (customer removed it), `incomplete` (a value is missing).
+
+Values (later wins): control default, baseline `parameters`, value on the baseline entry, assignment `values`,
+assignment `controlValues.<control>`. Exceptions need a reason, end date and approver; expired ones count as
+deviations again and are listed in `problems`; at most 366 days when `approvedAt` is given.
+
+## Command line
+
+```
+scalio-catalog validate <folders...>          check structure, references, texts
+scalio-catalog effective <assignment> <folders...> [--today 2026-11-01]
+scalio-catalog pack <folder> -o dist          sign (CATALOG_SIGNING_KEY or --key-file), --base for other packs
+scalio-catalog verify <file> --key <public>   check a package
+scalio-catalog keygen                         new key: seed to 1Password, public key into the apps
+scalio-catalog schema > catalog-v2.schema.json
+```
+
+## Editing in VS Code
+
+Install the YAML extension (Red Hat) and add to the workspace settings of `scalio_blueprint`:
+
+```json
+{ "yaml.schemas": { "./schema/catalog-v2.schema.json": ["controls/**/*.yaml", "baselines/**/*.yaml",
+  "resource-types/**/*.yaml", "pack.yaml"] } }
+```
+
+(`scalio-catalog schema > schema/catalog-v2.schema.json` writes the file.)
+
+## Release
+
+Bump `pyproject.toml` and `__version__`, CHANGELOG line, merge, then "Freigeben" in the Scalio Dev cockpit (or
+Actions -> Publish with the version). Publishes to PyPI via trusted publishing (no token).

scalio_catalog-0.1.0/README.md

@@ -0,0 +1,68 @@
+# scalio-catalog
+
+Shared code for the Scalio Blueprint governance catalog: one desired state per tenant, used by Foundry (roll
+out), Citadel (keep, drift) and Rosetta (document). Concept and decisions BP1-BP12:
+https://claude.ai/artifact/8PYfvHPm17KsooerLU95Ar (scalio-docs `concepts/governance-catalog.md`, ADR 0027).
+Format contract: scalio-docs `interfaces/catalog-format.md`.
+
+Nothing in this package is secret. The catalog content lives in the private repo `scalio_blueprint`; the signing
+seed stays in 1Password.
+
+## Documents
+
+| Kind | What | Owner |
+| --- | --- | --- |
+| `ResourceType` | Something in a tenant (name as in Microsoft365DSC/UTCM, e.g. `AADConditionalAccessPolicy`): properties, read/write endpoint, permission | Scalio |
+| `Control` | One security statement: match, desired values, parameters, severity, texts DE/EN, frameworks | Scalio, MSP, customer |
+| `Baseline` | Versioned bundle of controls with default values | Scalio, MSP |
+| `Assignment` | Tenant -> baseline@version, mode, channel, values, exceptions, own controls | customer |
+| `Pack` | Header of a signed package | Scalio, MSP |
+
+References: `id` (highest), `id@1.2.3` (exact), `id@^1.2` (same major, at least 1.2). Assignments name an exact
+version.
+
+## Use in an app
+
+```python
+from scalio_catalog import Catalog, compare, effective, plan_upgrade, summary, verify
+
+catalog = verify(package_bytes, TRUSTED_CATALOG_KEYS)        # signed pack from Compass or the image
+eff = effective(catalog, assignment)                         # baseline + customer layer, master untouched
+results = compare(eff, {c.id: read_resource(c) for c in eff.controls})   # app reads the tenant
+print(summary(results))                                      # {"counts": ..., "score": 92}
+plan = plan_upgrade(catalog, assignment, "scalio.kmu-standard@1.5.0")    # three-way, conflicts listed
+```
+
+`compare` statuses: `ok`, `drift`, `missing`, `excepted` (all deviations covered by an active exception),
+`not_read`, `removed` (customer removed it), `incomplete` (a value is missing).
+
+Values (later wins): control default, baseline `parameters`, value on the baseline entry, assignment `values`,
+assignment `controlValues.<control>`. Exceptions need a reason, end date and approver; expired ones count as
+deviations again and are listed in `problems`; at most 366 days when `approvedAt` is given.
+
+## Command line
+
+```
+scalio-catalog validate <folders...>          check structure, references, texts
+scalio-catalog effective <assignment> <folders...> [--today 2026-11-01]
+scalio-catalog pack <folder> -o dist          sign (CATALOG_SIGNING_KEY or --key-file), --base for other packs
+scalio-catalog verify <file> --key <public>   check a package
+scalio-catalog keygen                         new key: seed to 1Password, public key into the apps
+scalio-catalog schema > catalog-v2.schema.json
+```
+
+## Editing in VS Code
+
+Install the YAML extension (Red Hat) and add to the workspace settings of `scalio_blueprint`:
+
+```json
+{ "yaml.schemas": { "./schema/catalog-v2.schema.json": ["controls/**/*.yaml", "baselines/**/*.yaml",
+  "resource-types/**/*.yaml", "pack.yaml"] } }
+```
+
+(`scalio-catalog schema > schema/catalog-v2.schema.json` writes the file.)
+
+## Release
+
+Bump `pyproject.toml` and `__version__`, CHANGELOG line, merge, then "Freigeben" in the Scalio Dev cockpit (or
+Actions -> Publish with the version). Publishes to PyPI via trusted publishing (no token).

scalio_catalog-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scalio-catalog"
+version = "0.1.0"
+description = "Scalio Blueprint governance catalog (scalio.catalog/v2): check, effective desired state, drift, signed packs"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Proprietary" }
+dependencies = ["cryptography>=42", "jsonschema>=4.20", "pyyaml>=6"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+scalio-catalog = "scalio_catalog.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+scalio_catalog = ["schema/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B"]

scalio_catalog-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scalio_catalog-0.1.0/src/scalio_catalog/__init__.py

@@ -0,0 +1,19 @@
+"""Scalio Blueprint governance catalog (format scalio.catalog/v2, ADR 0027).
+
+Shared by Foundry (roll out), Citadel (keep) and Rosetta (document). Contract: scalio-docs
+interfaces/catalog-format.md.
+"""
+from .catalog import API_VERSION, Catalog, CatalogError, check_document, load_file, load_folder, parse_ref, schema
+from .compare import Deviation, Result, compare, summary
+from .effective import Effective, EffectiveControl, effective, render, require
+from .pack import key_id, load_private_key, new_seed, pack, public_key_b64, verify
+from .upgrade import Change, Plan, auto_update, next_versions, plan_upgrade
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "API_VERSION", "Catalog", "CatalogError", "Change", "Deviation", "Effective", "EffectiveControl", "Plan",
+    "Result", "auto_update", "check_document", "compare", "effective", "key_id", "load_file", "load_folder",
+    "load_private_key", "new_seed", "next_versions", "pack", "parse_ref", "plan_upgrade", "public_key_b64",
+    "render", "require", "schema", "summary", "verify",
+]

scalio_catalog-0.1.0/src/scalio_catalog/catalog.py

@@ -0,0 +1,296 @@
+"""Load and check catalog documents (scalio.catalog/v2).
+
+A catalog is a set of documents (ResourceType, Control, Baseline, optional Pack and Assignment), usually one YAML
+file each. `Catalog` indexes them by kind, id and version and resolves references like `id@^1.2`.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import re
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+from typing import Any, Iterable
+
+import yaml
+from jsonschema import Draft202012Validator
+
+API_VERSION = "scalio.catalog/v2"
+CATALOG_KINDS = ("ResourceType", "Control", "Baseline")
+PLACEHOLDER = re.compile(r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}")
+_REF = re.compile(r"^(?P<id>[A-Za-z0-9][A-Za-z0-9._-]*?)(?:@(?P<caret>\^)?(?P<ver>\d+(?:\.\d+){0,2}))?$")
+
+
+class CatalogError(Exception):
+    """A document or reference is not valid. `problems` lists every finding."""
+
+    def __init__(self, message: str, problems: list[str] | None = None):
+        super().__init__(message)
+        self.problems = problems or [message]
+
+
+def schema() -> dict:
+    """The JSON schema shipped with the package (also for editors: VS Code yaml.schemas)."""
+    return json.loads(resources.files("scalio_catalog").joinpath("schema/catalog-v2.schema.json").read_text("utf-8"))
+
+
+_VALIDATOR: Draft202012Validator | None = None
+
+
+def _validator() -> Draft202012Validator:
+    global _VALIDATOR
+    if _VALIDATOR is None:
+        _VALIDATOR = Draft202012Validator(schema(), format_checker=Draft202012Validator.FORMAT_CHECKER)
+    return _VALIDATOR
+
+
+def plain(value: Any) -> Any:
+    """YAML gives dates and datetimes as objects; the format stores them as ISO strings."""
+    if isinstance(value, dict):
+        return {str(k): plain(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [plain(v) for v in value]
+    if isinstance(value, (_dt.date, _dt.datetime)):
+        return value.isoformat()
+    return value
+
+
+def version_key(version: str) -> tuple[int, int, int]:
+    a, b, c = (version.split(".") + ["0", "0"])[:3]
+    return int(a), int(b), int(c)
+
+
+def parse_ref(ref: str) -> tuple[str, str | None, bool]:
+    """'id@^1.2' -> ('id', '1.2', True); 'id@1.2.3' -> ('id', '1.2.3', False); 'id' -> ('id', None, False)."""
+    m = _REF.match(ref or "")
+    if not m:
+        raise CatalogError(f"invalid reference '{ref}'")
+    return m["id"], m["ver"], bool(m["caret"])
+
+
+def ref_matches(version: str, wanted: str | None, caret: bool) -> bool:
+    if wanted is None:
+        return True
+    have = version_key(version)
+    parts = [int(p) for p in wanted.split(".")]
+    if caret:
+        return have[0] == parts[0] and have >= tuple(parts + [0] * (3 - len(parts)))
+    return list(have[: len(parts)]) == parts
+
+
+def check_texts(doc: Any, where: str = "") -> list[str]:
+    """German texts use 'ss', never the sharp s (Swiss spelling, all Scalio products)."""
+    found = []
+    if isinstance(doc, dict):
+        for k, v in doc.items():
+            found += check_texts(v, f"{where}.{k}" if where else str(k))
+    elif isinstance(doc, list):
+        for i, v in enumerate(doc):
+            found += check_texts(v, f"{where}[{i}]")
+    elif isinstance(doc, str) and "\u00df" in doc:
+        found.append(f"{where}: use 'ss' instead of the sharp s")
+    return found
+
+
+def check_document(doc: dict) -> list[str]:
+    """Structure (JSON schema) and spelling of one document. Returns the problems, empty when fine."""
+    doc = plain(doc)
+    problems = [f"{'/'.join(str(p) for p in e.absolute_path) or '(root)'}: {e.message}"
+                for e in sorted(_validator().iter_errors(doc), key=lambda e: list(map(str, e.absolute_path)))]
+    return problems + check_texts(doc)
+
+
+def placeholders(value: Any) -> set[str]:
+    if isinstance(value, str):
+        return set(PLACEHOLDER.findall(value))
+    if isinstance(value, dict):
+        return set().union(*(placeholders(v) for v in value.values())) if value else set()
+    if isinstance(value, list):
+        return set().union(*(placeholders(v) for v in value)) if value else set()
+    return set()
+
+
+def label(doc: dict) -> str:
+    return f"{doc.get('kind')} {doc.get('id') or doc.get('name')}@{doc.get('version', '-')}"
+
+
+@dataclass
+class Catalog:
+    """Documents by kind -> id -> version. Assignments and the Pack header are kept apart."""
+
+    docs: dict[str, dict[str, dict[str, dict]]] = field(default_factory=lambda: {k: {} for k in CATALOG_KINDS})
+    assignments: dict[str, dict] = field(default_factory=dict)
+    pack: dict | None = None
+
+    # ------------------------------------------------------------------ building
+
+    @classmethod
+    def from_documents(cls, documents: Iterable[dict], check: bool = True, base: "Catalog | None" = None) -> "Catalog":
+        """`base` is a catalog whose documents references may also point to (e.g. the Scalio base pack for an
+        MSP library or a premium pack). It is used for the checks only and not copied in."""
+        cat = cls()
+        problems: list[str] = []
+        for raw in documents:
+            doc = plain(raw)
+            found = check_document(doc) if check else []
+            if found:
+                problems += [f"{label(doc)}: {p}" for p in found]
+                continue
+            problems += cat._add(doc)
+        if check and not problems:
+            problems += (base.merged(cat) if base else cat).check_references()
+        if problems:
+            raise CatalogError(f"{len(problems)} problem(s) in the catalog", problems)
+        return cat
+
+    @classmethod
+    def from_folder(cls, *folders: str | Path, check: bool = True) -> "Catalog":
+        return cls.from_documents(load_folder(*folders), check=check)
+
+    def _add(self, doc: dict) -> list[str]:
+        kind = doc["kind"]
+        if kind == "Pack":
+            if self.pack is not None:
+                return ["more than one Pack header"]
+            self.pack = doc
+            return []
+        if kind == "Assignment":
+            if doc["id"] in self.assignments:
+                return [f"{label(doc)}: duplicate"]
+            self.assignments[doc["id"]] = doc
+            return []
+        versions = self.docs[kind].setdefault(doc["id"], {})
+        if doc["version"] in versions:
+            return [f"{label(doc)}: duplicate"]
+        versions[doc["version"]] = doc
+        return []
+
+    def merged(self, other: "Catalog") -> "Catalog":
+        """This catalog plus another one (e.g. Scalio master plus an MSP library). Same id+version must not differ."""
+        out = Catalog()
+        problems = []
+        for cat in (self, other):
+            for kind in CATALOG_KINDS:
+                for versions in cat.docs[kind].values():
+                    for doc in versions.values():
+                        have = out.docs[kind].get(doc["id"], {}).get(doc["version"])
+                        if have is not None and have != doc:
+                            problems.append(f"{label(doc)}: two different documents with the same version")
+                        elif have is None:
+                            out._add(doc)
+            out.assignments.update(cat.assignments)
+        if problems:
+            raise CatalogError("catalogs conflict", problems)
+        out.pack = self.pack
+        return out
+
+    # ------------------------------------------------------------------ lookup
+
+    def documents(self) -> list[dict]:
+        out = [self.pack] if self.pack else []
+        for kind in CATALOG_KINDS:
+            for vid in sorted(self.docs[kind]):
+                for ver in sorted(self.docs[kind][vid], key=version_key):
+                    out.append(self.docs[kind][vid][ver])
+        return out + [self.assignments[k] for k in sorted(self.assignments)]
+
+    def versions(self, kind: str, id_: str) -> list[str]:
+        return sorted(self.docs[kind].get(id_, {}), key=version_key)
+
+    def resolve(self, kind: str, ref: str) -> dict:
+        """Highest version that matches the reference."""
+        id_, wanted, caret = parse_ref(ref)
+        found = [v for v in self.versions(kind, id_) if ref_matches(v, wanted, caret)]
+        if not found:
+            raise CatalogError(f"{kind} '{ref}' not found")
+        return self.docs[kind][id_][found[-1]]
+
+    # ------------------------------------------------------------------ cross checks
+
+    def check_references(self) -> list[str]:
+        problems = []
+        for versions in self.docs["Control"].values():
+            for c in versions.values():
+                problems += [f"{label(c)}: {p}" for p in self._check_control(c)]
+        for versions in self.docs["Baseline"].values():
+            for b in versions.values():
+                for entry in b["controls"]:
+                    ref = entry if isinstance(entry, str) else entry["ref"]
+                    try:
+                        self.resolve("Control", ref)
+                    except CatalogError as e:
+                        problems.append(f"{label(b)}: {e}")
+        for a in self.assignments.values():
+            try:
+                self.resolve("Baseline", a["baseline"])
+            except CatalogError as e:
+                problems.append(f"{label(a)}: {e}")
+            for ref in a.get("add") or []:
+                try:
+                    self.resolve("Control", ref)
+                except CatalogError as e:
+                    problems.append(f"{label(a)}: {e}")
+        return problems
+
+    def _check_control(self, c: dict) -> list[str]:
+        problems = []
+        params = c.get("parameters") or {}
+        used = placeholders(c["resource"]["match"]) | placeholders(c["desired"])
+        problems += [f"placeholder '{{{{{p}}}}}' is not a declared parameter" for p in sorted(used - set(params))]
+        for name, p in params.items():
+            if p["type"] == "enum" and not p.get("values"):
+                problems.append(f"parameter '{name}': enum needs values")
+            if "default" in p and p["type"] == "enum" and p["default"] not in (p.get("values") or []):
+                problems.append(f"parameter '{name}': default is not one of the values")
+        try:
+            rt = self.resolve("ResourceType", c["resource"]["type"])
+        except CatalogError as e:
+            return problems + [str(e)]
+        props = rt["properties"]
+        for key, value in {**c["resource"]["match"], **c["desired"]}.items():
+            prop = props.get(key)
+            if prop is None:
+                problems.append(f"'{key}' is not a property of {rt['id']}")
+                continue
+            if placeholders(value):
+                continue
+            problems += [f"'{key}': {p}" for p in type_problems(prop, value)]
+        return problems
+
+
+def type_problems(prop: dict, value: Any) -> list[str]:
+    t = prop["type"]
+    ok = {
+        "string": isinstance(value, str),
+        "integer": isinstance(value, int) and not isinstance(value, bool),
+        "boolean": isinstance(value, bool),
+        "enum": isinstance(value, str),
+        "list": isinstance(value, list),
+        "object": isinstance(value, dict),
+    }[t]
+    if not ok:
+        return [f"expected {t}, got {type(value).__name__}"]
+    if t == "enum" and value not in prop.get("values", []):
+        return [f"'{value}' is not one of {prop.get('values')}"]
+    return []
+
+
+def load_file(path: str | Path) -> list[dict]:
+    """All documents of one YAML or JSON file (YAML may hold several, separated by ---)."""
+    text = Path(path).read_text("utf-8")
+    if str(path).endswith(".json"):
+        data = json.loads(text)
+        return data if isinstance(data, list) else [data]
+    return [plain(d) for d in yaml.safe_load_all(text) if d is not None]
+
+
+def load_folder(*folders: str | Path) -> list[dict]:
+    docs = []
+    for folder in folders:
+        folder = Path(folder)
+        files = [folder] if folder.is_file() else sorted(
+            p for p in folder.rglob("*") if p.suffix in (".yaml", ".yml", ".json") and p.is_file())
+        for f in files:
+            docs += load_file(f)
+    return docs

scalio_catalog-0.1.0/src/scalio_catalog/cli.py

@@ -0,0 +1,79 @@
+"""Command line: scalio-catalog validate|pack|verify|keygen|effective|schema."""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import os
+import sys
+from pathlib import Path
+
+from .catalog import Catalog, CatalogError, load_file, schema
+from .effective import effective
+from .pack import key_id, load_private_key, new_seed, pack, public_key_b64, verify
+
+
+def _base(paths) -> Catalog | None:
+    return Catalog.from_folder(*paths) if paths else None
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="scalio-catalog", description=__doc__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    v = sub.add_parser("validate", help="check folders or files")
+    v.add_argument("paths", nargs="+")
+    p = sub.add_parser("pack", help="check and sign a pack folder (key from CATALOG_SIGNING_KEY or --key-file)")
+    p.add_argument("folder")
+    p.add_argument("-o", "--out", default="dist")
+    p.add_argument("--key-file")
+    p.add_argument("--base", nargs="*", default=[], help="folders other packs refer to")
+    c = sub.add_parser("verify", help="check a signed package")
+    c.add_argument("file")
+    c.add_argument("--key", action="append", required=True, help="trusted public key (base64)")
+    sub.add_parser("keygen", help="new signing key: store the seed in 1Password, embed the public key")
+    e = sub.add_parser("effective", help="effective desired state of an assignment as JSON")
+    e.add_argument("assignment")
+    e.add_argument("paths", nargs="+", help="catalog folders")
+    e.add_argument("--today")
+    sub.add_parser("schema", help="print the JSON schema (for editors)")
+    a = ap.parse_args(argv)
+    try:
+        if a.cmd == "validate":
+            cat = Catalog.from_folder(*a.paths)
+            n = sum(len(v) for k in cat.docs.values() for v in k.values())
+            print(f"ok: {n} document(s), {len(cat.assignments)} assignment(s)")
+        elif a.cmd == "pack":
+            seed = Path(a.key_file).read_text().strip() if a.key_file else os.environ.get("CATALOG_SIGNING_KEY", "")
+            if not seed:
+                raise CatalogError("no signing key: set CATALOG_SIGNING_KEY or pass --key-file")
+            priv = load_private_key(seed)
+            name, data = pack(a.folder, priv, _base(a.base))
+            out = Path(a.out)
+            out.mkdir(parents=True, exist_ok=True)
+            (out / name).write_bytes(data)
+            print(f"{out / name}  key {key_id(public_key_b64(priv))}")
+        elif a.cmd == "verify":
+            cat = verify(Path(a.file).read_bytes(), a.key)
+            print(f"ok: {cat.pack['name']} {cat.pack['version']}")
+        elif a.cmd == "keygen":
+            seed = new_seed()
+            pub = public_key_b64(load_private_key(seed))
+            print(f"seed (secret, 1Password only): {seed}\npublic key: {pub}\nkey id: {key_id(pub)}")
+        elif a.cmd == "effective":
+            cat = Catalog.from_folder(*a.paths)
+            docs = load_file(a.assignment)
+            today = _dt.date.fromisoformat(a.today) if a.today else None
+            print(json.dumps(effective(cat, Catalog.from_documents(docs, base=cat).assignments[docs[0]["id"]],
+                                       today).as_dict(), indent=2, ensure_ascii=False))
+        elif a.cmd == "schema":
+            print(json.dumps(schema(), indent=2, ensure_ascii=False))
+    except CatalogError as err:
+        print(f"error: {err}", file=sys.stderr)
+        for line in err.problems:
+            print(f"  - {line}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())