ic-casals 0.2.0__py3-none-any.whl

access_code.py

@@ -0,0 +1,50 @@
+"""Invite access codes — pure, standard library only.
+
+A commander slot may be declared before anyone knows the principal that
+will hold it: the sheet (``environments.<env>.principals``) or a runtime
+``set_commander`` call lists ``sha256:<hex>`` — the checksum of a secret
+code — in place of a principal. Whoever presents the code to
+``claim_commander`` becomes that commander. The checksum is the only thing
+ever stored; the plaintext code lives with the person it was handed to.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+CODE_CHECKSUM_PREFIX = "sha256:"
+_HEX = frozenset("0123456789abcdef")
+
+
+def is_code_checksum(value) -> bool:
+    """True when ``value`` is written in the ``sha256:<hex>`` slot form
+    (regardless of whether the hex part is well-formed)."""
+    return isinstance(value, str) and value.strip().lower().startswith(CODE_CHECKSUM_PREFIX)
+
+
+def normalize_code_checksum(value: str) -> str:
+    """Canonical ``sha256:<64 lowercase hex>``; raises ValueError otherwise."""
+    v = (value or "").strip().lower()
+    if not v.startswith(CODE_CHECKSUM_PREFIX):
+        raise ValueError(f"invalid access-code checksum {value!r}: expected {CODE_CHECKSUM_PREFIX}<64 hex>")
+    digest = v[len(CODE_CHECKSUM_PREFIX):]
+    if len(digest) != 64 or not set(digest) <= _HEX:
+        raise ValueError(f"invalid access-code checksum {value!r}: expected {CODE_CHECKSUM_PREFIX}<64 hex>")
+    return CODE_CHECKSUM_PREFIX + digest
+
+
+def code_checksum(code: str) -> str:
+    """``sha256:<hex>`` of a code exactly as typed (surrounding whitespace stripped)."""
+    return CODE_CHECKSUM_PREFIX + hashlib.sha256((code or "").strip().encode("utf-8")).hexdigest()
+
+
+def checksums_equal(a: str, b: str) -> bool:
+    """Constant-time comparison of two checksum strings."""
+    a_b = (a or "").encode("utf-8")
+    b_b = (b or "").encode("utf-8")
+    if len(a_b) != len(b_b):
+        return False
+    acc = 0
+    for x, y in zip(a_b, b_b):
+        acc |= x ^ y
+    return acc == 0

auth.py

@@ -0,0 +1,89 @@
+"""Permission helpers — pure, no IC-runtime dependencies.
+
+The PERMISSIONS table and the three pure functions here form the
+'permission layer' that main.py wraps with its IC-runtime checks
+(_require_admin, _require_commander, …). Keeping this layer pure lets
+it be unit-tested without Basilisk or a running replica.
+"""
+
+# ── Commander permissions ──────────────────────────────────────────────────
+#
+# A commander (a principal appointed over a section or stand) may be granted
+# a subset of these capabilities.  The grant is stored as a comma-separated
+# string on the Section/Stand row; an empty string or "*" means "all"
+# (full control), which preserves the historical "commander can do
+# everything" behaviour.
+#
+# Each tuple is (key, human label, group) — the label/group drive the UI.
+
+PERMISSIONS = [
+    ("canister.create",    "Create canisters",           "Canisters"),
+    ("canister.deploy",    "Deploy / upgrade canisters", "Canisters"),
+    ("canister.delete",    "Delete canisters",           "Canisters"),
+    ("canister.rename",    "Rename canisters",           "Canisters"),
+    ("canister.tag",       "Set canister tags",          "Canisters"),
+    ("canister.snapshot",  "Create snapshots",           "Canisters"),
+    ("canister.revert",    "Revert to snapshot",         "Canisters"),
+    ("canister.lifecycle", "Start / stop canisters",     "Canisters"),
+    ("canister.topup",     "Top up cycles",              "Canisters"),
+    ("canister.shell",     "Run shell / exec code",      "Canisters"),
+    ("stand.create",       "Create stands",              "Stand"),
+    ("stand.rename",       "Rename stand",               "Stand"),
+    ("stand.delete",       "Delete stand",               "Stand"),
+    ("commander.assign",   "Appoint sub-commanders",     "Governance"),
+    ("subnet.whitelist",   "Manage subnet whitelist",    "Platform"),
+    ("wasm.upload",        "Upload files (WASMs, bundles) to the store", "Platform"),
+    ("wasm.authorize",     "Authorize / revoke catalog WASMs", "Platform"),
+]
+PERMISSION_KEYS = [p[0] for p in PERMISSIONS]
+
+
+def _parse_permissions(stored: str) -> list:
+    """Resolve a stored permission string into the list of granted keys.
+
+    Empty or "*" => full access (every known permission). Otherwise the
+    comma-separated subset, filtered to known keys only.
+    """
+    s = (stored or "").strip()
+    if s == "" or s == "*":
+        return list(PERMISSION_KEYS)
+    granted = [k.strip() for k in s.split(",") if k.strip()]
+    return [k for k in granted if k in PERMISSION_KEYS]
+
+
+def _normalize_permissions(perms) -> str:
+    """Turn an incoming permissions value (list or str) into the stored form.
+
+    "<group>.*" expands to every key of that group. A set covering every
+    permission is collapsed to "*". Unknown keys are dropped. None => ""
+    (full access, unchanged).
+    """
+    if perms is None:
+        return ""
+    if isinstance(perms, str):
+        keys = [k.strip() for k in perms.split(",") if k.strip()]
+    else:
+        keys = [str(k).strip() for k in perms if str(k).strip()]
+    if "*" in keys:
+        return "*"
+    for glob in [k for k in keys if k.endswith(".*")]:  # "canister.*" → every canister.<x> key
+        keys += [k for k in PERMISSION_KEYS if k.startswith(glob[:-1])]
+    keys = [k for k in PERMISSION_KEYS if k in keys]
+    if set(keys) >= set(PERMISSION_KEYS):
+        return "*"
+    return ",".join(keys)
+
+
+def _has_permission(stored: str, permission: str) -> bool:
+    """Return True if `stored` grants `permission` (empty permission always True)."""
+    if not permission:
+        return True
+    granted = _parse_permissions(stored)
+    if permission in granted:
+        return True
+    # Governance commanders (can appoint sub-commanders) may manage the
+    # platform-wide subnet whitelist even on legacy permission rows that
+    # pre-date the ``subnet.whitelist`` key.
+    if permission == "subnet.whitelist" and "commander.assign" in granted:
+        return True
+    return False

casals_cli/__init__.py

@@ -0,0 +1,18 @@
+"""Casals CLI v2 — declarative orchestra bootstrap and reconciliation."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# Keep in lockstep with [project].version in pyproject.toml (publish-pypi.yml checks).
+__version__ = "0.2.0"
+
+_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+_SRC = os.path.join(_ROOT, "src")
+if _SRC not in sys.path:
+    sys.path.insert(0, _SRC)
+if _ROOT not in sys.path:
+    sys.path.insert(0, _ROOT)
+
+__all__ = ["main", "__version__"]

casals_cli/bindings.py

@@ -0,0 +1,159 @@
+"""Runtime bindings: sheet name → canister id per environment."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+from sheetv2 import CONDUCTOR_NAMES
+
+
+
+def bindings_dir() -> str:
+    """`$CASALS_HOME` (tests, CI) or `~/.casals`."""
+    return os.environ.get("CASALS_HOME") or os.path.expanduser("~/.casals")
+
+
+@dataclass
+class Bindings:
+    sheet_name: str
+    env: str
+    network_url: str
+    deployer: str
+    conductor: dict[str, str] = field(default_factory=dict)
+    created_at: str = ""
+    backend_id: str = ""
+    icp_project_dir: str = ""
+    conductor_module_hashes: dict[str, str] = field(default_factory=dict)
+    asset_dist_hashes: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def casals_backend_id(self) -> str:
+        return self.backend_id or self.conductor.get(CONDUCTOR_NAMES["backend"], "")
+
+    def path(self) -> str:
+        safe = self.sheet_name.replace("/", "_")
+        return os.path.join(bindings_dir(), f"{safe}.{self.env}.json")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "sheet_name": self.sheet_name,
+            "env": self.env,
+            "network_url": self.network_url,
+            "deployer": self.deployer,
+            "conductor": dict(self.conductor),
+            "backend_id": self.backend_id or self.casals_backend_id,
+            "created_at": self.created_at or datetime.now(timezone.utc).isoformat(),
+            "icp_project_dir": self.icp_project_dir,
+            "conductor_module_hashes": dict(self.conductor_module_hashes),
+            "asset_dist_hashes": dict(self.asset_dist_hashes),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Bindings":
+        conductor = data.get("conductor") or {}
+        backend = (data.get("backend_id") or conductor.get(CONDUCTOR_NAMES["backend"]) or "").strip()
+        return cls(
+            sheet_name=str(data.get("sheet_name") or ""),
+            env=str(data.get("env") or ""),
+            network_url=str(data.get("network_url") or ""),
+            deployer=str(data.get("deployer") or ""),
+            conductor={k: str(v) for k, v in conductor.items()},
+            created_at=str(data.get("created_at") or ""),
+            backend_id=backend,
+            icp_project_dir=str(data.get("icp_project_dir") or ""),
+            conductor_module_hashes={
+                k: str(v) for k, v in (data.get("conductor_module_hashes") or {}).items()
+            },
+            asset_dist_hashes={
+                k: str(v) for k, v in (data.get("asset_dist_hashes") or {}).items()
+            },
+        )
+
+    def save(self) -> None:
+        os.makedirs(bindings_dir(), exist_ok=True)
+        if not self.created_at:
+            self.created_at = datetime.now(timezone.utc).isoformat()
+        with open(self.path(), "w", encoding="utf-8") as f:
+            json.dump(self.to_dict(), f, indent=2)
+            f.write("\n")
+
+    def remove(self) -> None:
+        path = self.path()
+        if os.path.exists(path):
+            os.remove(path)
+
+
+def load_bindings(sheet_name: str, env: str) -> Bindings | None:
+    b = Bindings(sheet_name=sheet_name, env=env, network_url="", deployer="")
+    path = b.path()
+    if not os.path.isfile(path):
+        return None
+    with open(path, encoding="utf-8") as f:
+        return Bindings.from_dict(json.load(f))
+
+
+def resolve_backend_id(bindings: Bindings | None, conductor_override: str | None) -> str:
+    if conductor_override:
+        return conductor_override.strip()
+    if bindings and bindings.casals_backend_id:
+        return bindings.casals_backend_id
+    return ""
+
+
+def live_bindings(ic, sheet_name: str, env: str, conductor_override: str | None = None) -> tuple[str, dict[str, str]]:
+    """(backend id, name → canister id) for an orchestra: local bindings file + the
+    conductor's `get_bindings` (stand canisters are only known to the conductor)."""
+    local = load_bindings(sheet_name, env)
+    backend = resolve_backend_id(local, conductor_override)
+    if not backend:
+        raise RuntimeError("no conductor; run casals up or pass --conductor")
+    ids = dict(local.conductor) if local else {}
+    res = ic.query(backend, "get_bindings")
+    if isinstance(res, dict) and res.get("bindings"):
+        ids.update(res["bindings"])
+    ids[CONDUCTOR_NAMES["backend"]] = backend
+    return backend, ids
+
+
+def find_bindings_for_env(env: str, conductor: str | None = None) -> Bindings | None:
+    """Locate a bindings file for ``env``, optionally matching ``conductor``."""
+    if not os.path.isdir(bindings_dir()):
+        return None
+    matches: list[Bindings] = []
+    suffix = f".{env}.json"
+    for fname in os.listdir(bindings_dir()):
+        if not fname.endswith(suffix):
+            continue
+        path = os.path.join(bindings_dir(), fname)
+        try:
+            with open(path, encoding="utf-8") as f:
+                b = Bindings.from_dict(json.load(f))
+        except (OSError, json.JSONDecodeError, TypeError):
+            continue
+        if conductor:
+            cid = conductor.strip()
+            if b.backend_id != cid and b.casals_backend_id != cid:
+                continue
+        matches.append(b)
+    if not matches:
+        return None
+    if len(matches) == 1:
+        return matches[0]
+    if conductor:
+        return matches[0]
+    raise RuntimeError(
+        f"multiple bindings for env {env!r}; pass --conductor or run from a named sheet"
+    )
+
+
+def live_stands(tree: dict) -> dict[str, dict]:
+    """stand name → {section, members, built} from the conductor's `get_tree`
+    (`built` absent = an older conductor: treat the stand as finished)."""
+    return {st.get("name", ""): {"section": sec.get("name", ""), "members": st.get("members") or [],
+                                 "built": bool(st.get("built", True))}
+            for sec in (tree.get("sections") or []) if isinstance(sec, dict)
+            for st in sec.get("stands") or [] if isinstance(st, dict)}

casals_cli/bundle.py

@@ -0,0 +1,291 @@
+"""Asset bundles: a frontend's built ``dist/`` as one hashed, versioned artifact.
+
+The spec is ``docs/BUNDLES.md``. In short:
+
+* A bundle is a set of files (``path -> bytes``); ``path`` is relative, uses ``/``,
+  never starts with ``/`` or contains ``..``. ``index.html`` must be at the root.
+* Every consumer — the sheet pin, the store, the conductor, the browser — agrees
+  on one **bundle hash**: sha256 over the text ``"<sha256>  <path>\\n"`` per
+  file, sorted by path (the ``sha256sum`` format, so ``sha256sum -c`` can
+  check an unpacked bundle against its manifest). Only content files count;
+  the manifest itself is excluded.
+* The transport is a canonical ``.tgz``: GNU tar, entries sorted by path,
+  mtime 0, uid/gid 0, mode 0644, no directory entries, gzip with no
+  timestamp or name — so the same files give the same bytes on every machine.
+  It carries the manifest at ``.casals-bundle.json`` (a dotfile, so it cannot
+  collide with a PWA's ``manifest.json``).
+"""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import io
+import json
+import os
+import tarfile
+from typing import Iterable
+
+from sheetv2 import BUNDLE_MANIFEST, bundle_hash as _shared_bundle_hash
+
+FORMAT = "casals-bundle/1"
+MANIFEST_NAME = BUNDLE_MANIFEST
+INDEX = "index.html"
+
+
+class BundleError(ValueError):
+    pass
+
+
+# ── hashing ──────────────────────────────────────────────────────────────────
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def file_hashes(files: dict[str, bytes]) -> dict[str, str]:
+    return {p: sha256_hex(b) for p, b in files.items() if p != MANIFEST_NAME}
+
+
+def manifest_text(hashes: dict[str, str]) -> str:
+    """The ``sha256sum`` listing the bundle hash is taken over. Sorted by path,
+    one ``<sha256>  <path>`` line each, trailing newline; the manifest file
+    itself never appears in it."""
+    return "".join(f"{hashes[p]}  {p}\n" for p in sorted(hashes) if p != MANIFEST_NAME)
+
+
+def bundle_hash(hashes: dict[str, str]) -> str:
+    """sha256 of :func:`manifest_text`. The one number every consumer compares;
+    the definition lives in ``sheetv2`` so the conductor uses the same one."""
+    return _shared_bundle_hash(hashes)
+
+
+def manifest(hashes: dict[str, str], sizes: dict[str, int] | None = None) -> dict:
+    hashes = {p: h for p, h in hashes.items() if p != MANIFEST_NAME}
+    return {
+        "format": FORMAT,
+        "bundle_sha256": bundle_hash(hashes),
+        "files": {
+            p: ({"sha256": hashes[p], "size": sizes[p]} if sizes and p in sizes else {"sha256": hashes[p]})
+            for p in sorted(hashes)
+        },
+    }
+
+
+# ── validation ───────────────────────────────────────────────────────────────
+
+
+def check_path(path: str) -> str:
+    p = path.replace(os.sep, "/")
+    if not p or p.startswith("/") or p.startswith("./") or "\\" in p:
+        raise BundleError(f"bundle path must be relative and use '/': {path!r}")
+    parts = p.split("/")
+    if any(part in ("", ".", "..") for part in parts):
+        raise BundleError(f"bundle path may not contain '', '.' or '..' segments: {path!r}")
+    return p
+
+
+def validate(files: dict[str, bytes]) -> None:
+    """A bundle is non-empty, has ``index.html`` at its root and only safe paths."""
+    content = {p: b for p, b in files.items() if p != MANIFEST_NAME}
+    if not content:
+        raise BundleError("bundle is empty")
+    for p in content:
+        check_path(p)
+    if INDEX not in content:
+        raise BundleError(f"bundle has no {INDEX} at its root")
+
+
+# ── directories ──────────────────────────────────────────────────────────────
+
+
+def read_dir(root: str) -> dict[str, bytes]:
+    """Every regular file under ``root`` (symlinks followed), keyed by its
+    forward-slash relative path, sorted. A manifest already on disk is skipped:
+    it is regenerated."""
+    if not os.path.isdir(root):
+        raise BundleError(f"not a directory: {root}")
+    out: dict[str, bytes] = {}
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=True):
+        dirnames.sort()
+        for fn in sorted(filenames):
+            full = os.path.join(dirpath, fn)
+            rel = check_path(os.path.relpath(full, root))
+            if rel == MANIFEST_NAME:
+                continue
+            with open(full, "rb") as f:
+                out[rel] = f.read()
+    return dict(sorted(out.items()))
+
+
+# ── tarballs ─────────────────────────────────────────────────────────────────
+
+
+def _tarinfo(name: str, size: int) -> tarfile.TarInfo:
+    ti = tarfile.TarInfo(name)
+    ti.size = size
+    ti.mtime = 0
+    ti.mode = 0o644
+    ti.uid = ti.gid = 0
+    ti.uname = ti.gname = ""
+    ti.type = tarfile.REGTYPE
+    return ti
+
+
+def write_tgz(files: dict[str, bytes], include_manifest: bool = True) -> tuple[bytes, dict]:
+    """Canonical ``.tgz`` bytes for ``files`` plus the manifest it carries.
+    Deterministic: same files, same bytes."""
+    validate(files)
+    content = {p: b for p, b in files.items() if p != MANIFEST_NAME}
+    hashes = file_hashes(content)
+    man = manifest(hashes, {p: len(b) for p, b in content.items()})
+    raw = io.BytesIO()
+    with tarfile.open(fileobj=raw, mode="w", format=tarfile.GNU_FORMAT) as tar:
+        entries = dict(sorted(content.items()))
+        if include_manifest:
+            entries[MANIFEST_NAME] = (json.dumps(man, indent=2, sort_keys=True) + "\n").encode("utf-8")
+        for name in sorted(entries):
+            data = entries[name]
+            tar.addfile(_tarinfo(name, len(data)), io.BytesIO(data))
+    gz = io.BytesIO()
+    with gzip.GzipFile(filename="", mode="wb", fileobj=gz, mtime=0, compresslevel=9) as g:
+        g.write(raw.getvalue())
+    return gz.getvalue(), man
+
+
+def read_tgz(data: bytes) -> tuple[dict[str, bytes], dict | None]:
+    """Files of a ``.tgz`` (or plain ``.tar``) bundle and its manifest if it has
+    one. Rejects unsafe paths and, when a manifest is present, any file whose
+    hash disagrees with it — a tampered or mis-packed bundle fails here, not
+    in a canister."""
+    if data[:2] == b"\x1f\x8b":
+        data = gzip.decompress(data)
+    files: dict[str, bytes] = {}
+    with tarfile.open(fileobj=io.BytesIO(data), mode="r:") as tar:
+        for member in tar:
+            if member.isdir():
+                continue
+            if not member.isfile():
+                raise BundleError(f"bundle contains a non-file entry: {member.name!r}")
+            name = member.name[2:] if member.name.startswith("./") else member.name
+            name = check_path(name) if name != MANIFEST_NAME else name
+            f = tar.extractfile(member)
+            files[name] = f.read() if f else b""
+    man = None
+    if MANIFEST_NAME in files:
+        try:
+            man = json.loads(files.pop(MANIFEST_NAME).decode("utf-8"))
+        except ValueError as exc:
+            raise BundleError(f"{MANIFEST_NAME} is not JSON: {exc}") from exc
+        check_manifest(files, man)
+    validate(files)
+    return dict(sorted(files.items())), man
+
+
+def check_manifest(files: dict[str, bytes], man: dict) -> None:
+    if not isinstance(man, dict) or man.get("format") != FORMAT:
+        raise BundleError(f"unsupported bundle manifest format: {man.get('format') if isinstance(man, dict) else man!r}")
+    listed = {p: (m or {}).get("sha256", "") for p, m in (man.get("files") or {}).items()}
+    actual = file_hashes(files)
+    if listed != actual:
+        missing = sorted(set(listed) - set(actual))
+        extra = sorted(set(actual) - set(listed))
+        changed = sorted(p for p in set(listed) & set(actual) if listed[p] != actual[p])
+        raise BundleError(
+            "bundle does not match its manifest"
+            + (f"; missing {missing}" if missing else "")
+            + (f"; unlisted {extra}" if extra else "")
+            + (f"; changed {changed}" if changed else "")
+        )
+    if man.get("bundle_sha256") != bundle_hash(actual):
+        raise BundleError("manifest bundle_sha256 does not match its file list")
+
+
+# ── sources ──────────────────────────────────────────────────────────────────
+
+
+def is_bundle_file(path_or_url: str) -> bool:
+    p = path_or_url.split("?", 1)[0].lower()
+    return p.endswith((".tgz", ".tar.gz", ".tar"))
+
+
+def read_bundle(path: str) -> dict[str, bytes]:
+    """A bundle from disk: a directory or a ``.tgz``/``.tar``. Validated."""
+    if os.path.isdir(path):
+        files = read_dir(path)
+        validate(files)
+        return files
+    if not os.path.isfile(path):
+        raise BundleError(f"bundle not found: {path}")
+    with open(path, "rb") as f:
+        files, _ = read_tgz(f.read())
+    return files
+
+
+def sha256sum_line(digest: str, filename: str) -> str:
+    return f"{digest}  {filename}\n"
+
+
+def summary(files: dict[str, bytes]) -> dict:
+    hashes = file_hashes(files)
+    return {
+        "bundle_sha256": bundle_hash(hashes),
+        "files": len(hashes),
+        "bytes": sum(len(b) for p, b in files.items() if p != MANIFEST_NAME),
+    }
+
+
+def diff(hashes_a: dict[str, str], hashes_b: dict[str, str]) -> dict[str, list[str]]:
+    """Paths to upload (new or changed in ``b``) and to delete (only in ``a``)
+    when moving a namespace or canister from bundle ``a`` to bundle ``b``."""
+    a = {p: h for p, h in hashes_a.items() if p != MANIFEST_NAME}
+    b = {p: h for p, h in hashes_b.items() if p != MANIFEST_NAME}
+    return {
+        "upload": sorted(p for p, h in b.items() if a.get(p) != h),
+        "delete": sorted(p for p in a if p not in b),
+    }
+
+
+def iter_lines(hashes: dict[str, str]) -> Iterable[str]:
+    yield from manifest_text(hashes).splitlines()
+
+
+def main(argv: list[str] | None = None) -> int:
+    """``python3 -m casals_cli.bundle <dist> -o <out.tgz>`` — the ``casals bundle``
+    command without the rest of the CLI's dependencies (stdlib only), for
+    product release workflows that clone Casals and pack their frontend."""
+    import argparse
+    import sys
+
+    ap = argparse.ArgumentParser(prog="casals_cli.bundle", description="pack a built frontend into a canonical hashed .tgz (docs/BUNDLES.md)")
+    ap.add_argument("source", help="dist directory (or, with --verify, a directory or .tgz)")
+    ap.add_argument("-o", "--output", default="bundle.tgz")
+    ap.add_argument("--manifest", default=None, help="also write the manifest JSON here")
+    ap.add_argument("--verify", action="store_true", help="only read and validate; print the bundle hash")
+    args = ap.parse_args(argv)
+    try:
+        if args.verify:
+            info = summary(read_bundle(args.source))
+            print(f"{args.source}: {info['files']} file(s), {info['bytes']} bytes, bundle sha256 {info['bundle_sha256']}")
+            return 0
+        files = read_dir(args.source) if os.path.isdir(args.source) else read_bundle(args.source)
+        data, man = write_tgz(files)
+    except BundleError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    with open(args.output, "wb") as f:
+        f.write(data)
+    with open(args.output + ".sha256", "w", encoding="utf-8") as f:
+        f.write(sha256sum_line(sha256_hex(data), os.path.basename(args.output)))
+    if args.manifest:
+        with open(args.manifest, "w", encoding="utf-8") as f:
+            json.dump(man, f, indent=2, sort_keys=True)
+            f.write("\n")
+    print(f"{args.output}: {len(man['files'])} file(s), {len(data)} bytes gzipped")
+    print(f"  bundle sha256 {man['bundle_sha256']}   (pin this in registry.publish)")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())