katalyst-taxonomy-cli 2.0.1a3__tar.gz → 2.0.1a4__tar.gz

{katalyst_taxonomy_cli-2.0.1a3 → katalyst_taxonomy_cli-2.0.1a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: katalyst-taxonomy-cli
-Version: 2.0.1a3
+Version: 2.0.1a4
 Summary: CLI for katalyst-taxonomy — the kata command
 Author: eSimplicity
 License: Proprietary

{katalyst_taxonomy_cli-2.0.1a3 → katalyst_taxonomy_cli-2.0.1a4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-taxonomy-cli"
-version = "2.0.1a3"
+version = "2.0.1a4"
 description = "CLI for katalyst-taxonomy — the kata command"
 license = { text = "Proprietary" }
 requires-python = ">=3.12"

{katalyst_taxonomy_cli-2.0.1a3 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/app.py

@@ -206,6 +206,13 @@ def _installed_katalyst_packages() -> list[tuple[str, str]]:
     return sorted(found.items())
 
 
+def _schema_versions() -> list[tuple[str, str]]:
+    """Every schema installed (katalyst-core, and each bundle), with its version."""
+    from katalyst_engine.evolution import installed_releases
+
+    return [(release.name, str(release.version)) for release in installed_releases()]
+
+
 def _print_version(ctx: click.Context, _param: click.Parameter, value: bool) -> None:
     if not value or ctx.resilient_parsing:
         return
@@ -217,6 +224,12 @@ def _print_version(ctx: click.Context, _param: click.Parameter, value: bool) ->
     click.echo(f"kata {__version__}")
     for name, version in _installed_katalyst_packages():
         click.echo(f"  {name} {version}")
+    click.echo("schemas:")
+    try:
+        for name, version in _schema_versions():
+            click.echo(f"  {name} {version}")
+    except Exception as exc:  # a bundle that does not load must not hide the versions
+        click.echo(f"  unavailable: {exc}")
     for line in install_lines():
         click.echo(line)
     try:
@@ -274,8 +287,8 @@ def _select_home(ctx: click.Context, _param: click.Parameter, value: str | None)
     # Not eager, so it runs after --home (which is) and reports the home chosen.
     callback=_print_version,
     help=(
-        "Show the kata version, every installed Katalyst package, the install (and what it "
-        "was built from) and the home, then exit."
+        "Show the kata version, every installed Katalyst package, the schema bundles with "
+        "their versions, the install (and what it was built from) and the home, then exit."
     ),
 )
 @click.option(
@@ -525,6 +538,7 @@ def _register_core_commands() -> None:
         relate,
         relocate,
         remove,
+        rescaffold,
         resolve,
         rollback,
         self_update,
@@ -582,6 +596,7 @@ def _register_core_commands() -> None:
     tax.add_command(export.export)
     tax.add_command(backend.backend)
     tax.add_command(remove.remove)
+    tax.add_command(rescaffold.rescaffold)
 
 
 def resolve_plugin_commands() -> None:

{katalyst_taxonomy_cli-2.0.1a3 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/config_schemas.py

@@ -60,7 +60,11 @@ def build_schemas_payload(
     from katalyst_taxonomy.config.schemas import selection_from_config
     from katalyst_taxonomy.engine import bridge
     from katalyst_taxonomy.services.schema_gate import check_declared_bundles
-    from katalyst_taxonomy.services.schema_report import schemas_payload
+    from katalyst_taxonomy.services.schema_report import (
+        core_schema,
+        schema_versions,
+        schemas_payload,
+    )
     from katalyst_taxonomy.sources.template_resolver import TemplateResolver
 
     effective = config_resolver().resolve(profile=profile)
@@ -90,6 +94,8 @@ def build_schemas_payload(
                 if candidate.distribution
             },
             declared=declared,
+            schema_versions=schema_versions(candidates),
+            core_schema=core_schema(),
             scaffold_providers=resolver.scaffold_template_providers(),
             repo_root=None,
             filesystem=RealFilesystem(),
@@ -155,19 +161,24 @@ def _render_text(out: OutputPort, payload: dict[str, Any]) -> None:
         ]
     )
 
+    core = payload.get("core")
+    if core:
+        out.key_value([("katalyst-core schema", _schema_text(core))])
+
     out.heading("Bundles")
     bundles: list[dict[str, Any]] = payload["bundles"]
     if not bundles:
         out.info("No schema bundles discovered.")
     else:
         out.table(
-            ["", "bundle", "distribution", "version", "kinds", "note"],
+            ["", "bundle", "distribution", "version", "schema", "kinds", "note"],
             [
                 [
                     "*" if entry["enabled"] else "x",
                     str(entry["name"]),
                     str(entry.get("distribution") or "-"),
                     str(entry.get("resolvedVersion") or entry["version"] or "-"),
+                    _schema_text(entry.get("schema")),
                     str(len(entry["kinds"])),
                     str(
                         entry["reason"] or entry.get("sourceWarning") or entry["entryPoint"] or "-"
@@ -239,6 +250,19 @@ def _render_text(out: OutputPort, payload: dict[str, Any]) -> None:
         )
 
 
+def _schema_text(schema: dict[str, Any] | None) -> str:
+    """``9.0.0 (unreleased; latest archived 8.0.0)``: a schema's version and archive state."""
+    if not schema:
+        return "-"
+    from katalyst_engine.core.version import Version
+    from katalyst_engine.evolution import ArchiveState
+
+    archive = schema["archive"]
+    latest = archive["latest"]
+    state = ArchiveState(archive["state"], Version.parse(latest) if latest else None)
+    return f"{schema['version']} ({state})"
+
+
 def attach(group: click.Group) -> None:
     """Add ``schemas`` to the ``kata config`` group.
 

{katalyst_taxonomy_cli-2.0.1a3 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/core.py

@@ -23,6 +23,12 @@
                                        the diff
     kata core schema archive --bundle B
                                        archive the current modules as the released version
+    kata core schema docs [PATH...] [--bundle B] [--check] [--kind K]
+                                       write the generated field tables of the pages
+                                       under PATH; --check fails when any is stale
+    kata core schema changelog [--bundle B] [--from VERSION]
+                                       the "Schema changes" section of a release: what was
+                                       added, what broke, and the migration step for each
 
 Records and graphs are read against every installed module (``katalyst_core.modules``).
 """
@@ -466,3 +472,118 @@ def schema_archive(bundle: str) -> None:
     except (FileExistsError, SchemaVersionMismatchError) as exc:
         raise click.ClickException(str(exc)) from exc
     click.echo(f"Archived {release.name} {release.version} in {target}")
+
+
+# Named from the function (``docs``), so no command-name literal reads as a bundle name.
+@schema.command()
+@click.argument("paths", nargs=-1, type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--bundle",
+    "bundle",
+    default=None,
+    help="Read kinds from this schema only (needed when two define the same kind).",
+)
+@click.option(
+    "--check",
+    is_flag=True,
+    help="Write nothing; fail when a generated region is stale (for CI).",
+)
+@click.option(
+    "--kind",
+    "kind",
+    default=None,
+    help="Print the markdown for one kind (to start a page), and write nothing.",
+)
+def docs(paths: tuple[Path, ...], bundle: str | None, check: bool, kind: str | None) -> None:
+    """Write the generated field tables of the markdown pages under PATH.
+
+    A page marks where a table goes with a line of its own, ``<!-- generated:kind:NAME -->``
+    (a kind's parent and fields: type, required, allowed values, references and their
+    relationship types, descriptions) or ``<!-- generated:wing:NAME -->`` (a wing's kinds:
+    where each is stored and its parent), and closes it with ``<!-- /generated -->``. The
+    text between is rewritten from the schemas' LinkML modules; everything else on the page
+    is yours.
+    """
+    from katalyst_engine.schema_docs import (
+        DocsError,
+        RegionError,
+        catalog_from_releases,
+        page_files,
+        refresh_page,
+        render_kind,
+    )
+
+    if kind is None and not paths:
+        raise click.UsageError("name the pages to write: one or more files or directories")
+    catalog = catalog_from_releases(_releases(bundle))
+    try:
+        if kind is not None:
+            click.echo(render_kind(catalog.kind(kind, bundle=bundle)))
+            return
+        stale_total = 0
+        for page in page_files(paths):
+            text = page.read_text(encoding="utf-8")
+            try:
+                new_text, stale = refresh_page(text, catalog, bundle=bundle)
+            except (RegionError, DocsError) as exc:
+                raise click.ClickException(f"{page}: {exc}") from exc
+            stale_total += len(stale)
+            for region in stale:
+                click.echo(f"{page}:{region.line}: generated:{region.label} is stale")
+            if stale and not check:
+                page.write_text(new_text, encoding="utf-8")
+    except DocsError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if check:
+        if stale_total:
+            raise click.ClickException(
+                f"{stale_total} generated region(s) are stale; "
+                f"run kata core schema docs {' '.join(str(p) for p in paths)}"
+            )
+        click.echo("generated regions are current")
+    else:
+        click.echo(f"Updated {stale_total} generated region(s)")
+
+
+@schema.command("changelog")
+@_BUNDLE
+@click.option(
+    "--from",
+    "since",
+    default=None,
+    help="The archived version to compare with (default: the latest).",
+)
+@click.option(
+    "--heading-level",
+    "level",
+    type=click.IntRange(1, 5),
+    default=2,
+    show_default=True,
+    help="The level of the section's heading (2: ##).",
+)
+def schema_changelog(bundle: str | None, since: str | None, level: int) -> None:
+    """The "Schema changes" section of a release, from the classified diff and the migration.
+
+    For each schema whose modules changed since its last archived version: what was added,
+    what broke, and for each breaking change the `kata tax migrate` step that handles it
+    (or the reason it is accepted). Markdown on stdout, for the release notes.
+    """
+    from katalyst_engine.core.version import Version
+    from katalyst_engine.evolution import build_changelog, render_changelog
+
+    logs: list[Any] = []
+    for release in _releases(bundle):
+        try:
+            old = Version.parse(since) if since else None
+            log = build_changelog(release, old)
+        except (ValueError, FileNotFoundError) as exc:
+            raise click.ClickException(str(exc)) from exc
+        if log is None:
+            click.echo(f"{release.name}: no released version is archived", err=True)
+        else:
+            logs.append(log)
+    text = render_changelog(logs, level=level)
+    if not text:
+        click.echo("No schema changes since the last released version.", err=True)
+        return
+    click.echo(text, nl=False)

{katalyst_taxonomy_cli-2.0.1a3 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/create.py

@@ -41,7 +41,24 @@ from katalyst_taxonomy_cli.context import CliContext
     "from_file",
     default=None,
     metavar="PATH",
-    help="Spec fields from a YAML or JSON file (- for stdin); --set applies over them.",
+    help=(
+        "Spec fields from a YAML or JSON file (- for stdin), or a whole document's spec, "
+        "labels and annotations; --set, --label and --annotation apply over them."
+    ),
+)
+@click.option(
+    "--label",
+    "label_pairs",
+    multiple=True,
+    metavar="KEY=VALUE",
+    help="Set a label (metadata.labels), which filters and permission grants match. Repeat.",
+)
+@click.option(
+    "--annotation",
+    "annotation_pairs",
+    multiple=True,
+    metavar="KEY=VALUE",
+    help="Set an annotation (metadata.annotations), a record nothing matches on. Repeat.",
 )
 @click.option("--target-dir", default=None, help="Override output directory.")
 @click.option(
@@ -75,6 +92,8 @@ def create(
     scaffold_variant: str | None,
     set_fields: tuple[str, ...],
     from_file: str | None,
+    label_pairs: tuple[str, ...],
+    annotation_pairs: tuple[str, ...],
     target_dir: str | None,
     backend_target: str | None,
     dry_run: bool,
@@ -96,6 +115,11 @@ def create(
     a value of its type (boolean, integer, list, map) and allowed values, a reference
     naming a node of the referenced kind.
 
+    --label KEY=VALUE and --annotation KEY=VALUE go in the node's metadata, on any kind.
+    A key is a name of letters, digits, '-', '_' and '.' (at most 63), optionally after a
+    DNS prefix and '/' (example.org/team); a label's value is such a name (or empty), an
+    annotation's any text.
+
     Examples:
 
         kata tax create layer api --under shop.backend --set audited=false --set tier=gold
@@ -105,15 +129,20 @@ def create(
         kata tax create capability checkout --under shop --set 'hooks=[{"on":"push","branches":["main"]}]'
 
         kata tax create stack web --under shop --set limits.log_level=debug
+
+        kata tax create layer api --under shop.backend --label team=payments --annotation source=docs/api.md
     """
     from katalyst_taxonomy.adapters.orchestration import run_create
     from katalyst_taxonomy.config.routing import split_backend_prefix
 
-    from katalyst_taxonomy_cli.fields import parse_set, read_spec_file
+    from katalyst_taxonomy_cli.fields import parse_pairs, parse_set, read_node_file
 
     from .._wiring import resolve_backend
 
     resolved_parent = parent or parent_alt
+    node_file = read_node_file(from_file)
+    labels = {**node_file.labels, **parse_pairs(label_pairs, option="--label")}
+    annotations = {**node_file.annotations, **parse_pairs(annotation_pairs, option="--annotation")}
 
     # The backend is `--backend`, or the `backend:` prefix of NAME. Without either, the
     # repository is the one the current directory is inside — even with one repository,
@@ -134,7 +163,9 @@ def create(
         description=description,
         owners=owners or (),
         fields=parse_set(set_fields),
-        spec=read_spec_file(from_file),
+        spec=node_file.spec,
+        labels=labels,
+        annotations=annotations,
         parent=resolved_parent,
         scaffold_variant=scaffold_variant,
         target_dir=target_dir,

{katalyst_taxonomy_cli-2.0.1a3 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/lifecycle.py

@@ -118,10 +118,12 @@ def import_(ctx: CliContext, file: Path, backend_target: str) -> None:
             resolved.backend,
             [cast("dict[str, Any]", d) for d in documents],
             create=lambda request: create_node(resolved.backend, request),
+            source=file,
         )
     except ImportError_ as exc:
         ctx.output.echo(f"Error: {exc}")
-        ctx.output.echo("Error: nothing was imported.")
+        if not exc.left_behind:
+            ctx.output.echo("Error: nothing was imported.")
         raise SystemExit(1) from exc
     for fqtn in created:
         ctx.output.echo(f"Imported: {resolved.name}:{fqtn}")

{katalyst_taxonomy_cli-2.0.1a3 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/plugin.py

@@ -79,7 +79,11 @@ def add_plugin(ctx: CliContext, source_uri: str, yes: bool) -> None:
 @click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
 @click.pass_obj
 def list_plugins(ctx: CliContext, as_json: bool) -> None:
-    """List plugins: entry-point packages and source installs, with their state."""
+    """List plugins: entry-point packages and source installs, with their state.
+
+    A plugin whose declared schema ranges the loaded schemas don't satisfy is
+    refused: listed, not activated, with the range and the loaded version.
+    """
     from katalyst_taxonomy.plugins.activation import current_activation
     from katalyst_taxonomy.plugins.registry import ORIGIN_SOURCE
     from katalyst_taxonomy.services.source_providers import declared_plugin_sources
@@ -102,6 +106,8 @@ def list_plugins(ctx: CliContext, as_json: bool) -> None:
                     "source": declared.get(name),
                     "enabled": activation.selection.is_enabled(name),
                     "active": activation.activated(name),
+                    "schemas": dict(manifest.schemas),
+                    "refused": activation.refused(name) or None,
                 }
             )
     for name, source in declared.items():
@@ -114,6 +120,8 @@ def list_plugins(ctx: CliContext, as_json: bool) -> None:
                     "source": source,
                     "enabled": activation.selection.is_enabled(name) if activation else True,
                     "active": False,
+                    "schemas": {},
+                    "refused": None,
                 }
             )
     rows.sort(key=lambda row: str(row["name"]))
@@ -125,9 +133,16 @@ def list_plugins(ctx: CliContext, as_json: bool) -> None:
         return
     ctx.output.echo(f"Plugins ({len(rows)}):")
     for row in rows:
-        state = "active" if row["active"] else ("enabled" if row["enabled"] else "disabled")
+        if row["active"]:
+            state = "active"
+        elif row["refused"]:
+            state = "refused"
+        else:
+            state = "enabled" if row["enabled"] else "disabled"
         source = f"  [{row['source']}]" if row["source"] else ""
         ctx.output.echo(f"  {row['name']}  v{row['version']}  {row['origin']}  {state}{source}")
+        if row["refused"]:
+            ctx.output.echo(f"    {row['refused']}")
 
 
 @plugin.command("remove")

katalyst_taxonomy_cli-2.0.1a4/src/katalyst_taxonomy_cli/commands/rescaffold.py

@@ -0,0 +1,149 @@
+"""kata tax rescaffold — re-render a node's scaffold at the installed template version.
+
+A node made from a scaffold variant keeps the files it was scaffolded with (a layer's
+``Dockerfile``, overlays, env files). Upgrading the bundle with ``kata tax add`` upgrades
+the template, not those files. This re-renders the node's template, as installed now,
+and merges it three ways with the node's files, the base being the template at the
+version the node records it was scaffolded from
+(:mod:`katalyst_taxonomy.services.rescaffold`).
+"""
+
+from __future__ import annotations
+
+import click
+
+from katalyst_taxonomy_cli.context import CliContext
+
+
+@click.command("rescaffold")
+@click.argument("address")
+@click.option(
+    "--backend", "backend_target", default=None, help="The backend, when ADDRESS has no prefix."
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Show what each file would become (the merge plan); write nothing.",
+)
+@click.option(
+    "--theirs",
+    "theirs",
+    is_flag=True,
+    help="Take the installed template's render whole, over local edits. Needs no base.",
+)
+@click.option(
+    "--ours",
+    "ours",
+    is_flag=True,
+    help="Keep every file as it is; only add the files the node does not have.",
+)
+@click.option(
+    "--base-source",
+    default="",
+    help=(
+        "A source holding the version the node was scaffolded from, when its files are "
+        "not in the home's cache."
+    ),
+)
+@click.pass_obj
+def rescaffold(
+    ctx: CliContext,
+    address: str,
+    backend_target: str | None,
+    dry_run: bool,
+    theirs: bool,
+    ours: bool,
+    base_source: str,
+) -> None:
+    """Re-render node ADDRESS's scaffold at the installed version, merged with its files.
+
+    The template is rendered as installed now (theirs) and as the version the node was
+    scaffolded from (the base: its metadata.annotations.templateBundleVersion), and each
+    file in the node's directory (ours) is merged three ways, as kata tax add merges a
+    bundle's files. Conflicts are written with markers, listed, and exit 1; the node is
+    then stamped with the installed version.
+
+    Examples:
+
+    \b
+        kata tax rescaffold local:shop.api.docker --dry-run
+        kata tax rescaffold local:shop.api.docker
+        kata tax rescaffold local:shop.api.docker --theirs
+    """
+    from katalyst_taxonomy.adapters.filesystem.real import RealFilesystem
+    from katalyst_taxonomy.adapters.orchestration import (
+        create_hooks,
+        load_taxonomy,
+        scaffold_extensions,
+    )
+    from katalyst_taxonomy.domain.template_merge import MergeMode, plan_lines
+    from katalyst_taxonomy.engine.accessors import get_source_path
+    from katalyst_taxonomy.engine.qualification import match_fqtn_in
+    from katalyst_taxonomy.ports.backend import repository_root_of
+    from katalyst_taxonomy.services.rescaffold import rescaffold_node
+    from katalyst_taxonomy.services.template_install import template_base_resolver
+
+    from .._wiring import resolve_backend
+
+    if theirs and ours:
+        raise click.UsageError("--theirs and --ours are each other's opposite; give one.")
+    mode: MergeMode = "theirs" if theirs else "ours" if ours else "merge"
+    resolved = resolve_backend(ctx, backend_target, address=address)
+    root = repository_root_of(resolved.backend)
+    if root is None:
+        raise click.ClickException(
+            f"Backend {resolved.name!r} keeps no working tree, so it has no scaffolded files."
+        )
+    resolution = match_fqtn_in(resolved.backend.load_documents(), resolved.address)
+    node = resolution.target
+    if node is None:
+        raise click.ClickException(
+            f"Node {resolved.address!r} not found in backend {resolved.name!r}."
+            if resolution.is_unresolved
+            else resolution.describe()
+        )
+    document = get_source_path(node)
+    if document is None or not document.is_file():
+        raise click.ClickException(f"{node.fqn} has no document in {root}.")
+    if not document.is_absolute():
+        document = root / document
+
+    outcome = rescaffold_node(
+        root,
+        node,
+        document,
+        filesystem=RealFilesystem(),
+        extensions=scaffold_extensions(),
+        base=template_base_resolver(ctx.templates, base_source=base_source),
+        mode=mode,
+        dry_run=dry_run,
+        create_hooks=create_hooks(),
+        load_taxonomy=lambda: load_taxonomy(root, profile=ctx.profile),
+    )
+    if not outcome.success:
+        ctx.output.echo(f"Error: {outcome.error}")
+        raise SystemExit(1)
+    change = (
+        f"{outcome.from_version} -> {outcome.to_version}"
+        if outcome.from_version
+        else outcome.to_version or "?"
+    )
+    where = f"{resolved.name}:{outcome.fqtn}"
+    heading = "Plan for" if dry_run else "Rescaffolded"
+    suffix = " (dry run)" if dry_run else ""
+    ctx.output.echo(
+        f"{heading} {where}: template {outcome.variant}, bundle {outcome.bundle or '?'} "
+        f"{change}{suffix}:"
+    )
+    plan = outcome.plan
+    rows = plan.as_dicts() if plan is not None else []
+    for line in plan_lines(rows, every=dry_run):
+        ctx.output.echo(line)
+    conflicts = plan.conflicts if plan is not None else ()
+    if conflicts and not dry_run:
+        ctx.output.echo(
+            f"{len(conflicts)} file(s) have conflicts; resolve the markers in them:\n"
+            + "\n".join(f"  {f.path}" for f in conflicts)
+        )
+    if conflicts:
+        raise SystemExit(1)

{katalyst_taxonomy_cli-2.0.1a3 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/update.py

@@ -49,6 +49,24 @@ def _pairs(values: tuple[str, ...], option: str) -> dict[str, list[str]]:
     help="Remove a value from a list field.",
 )
 @click.option("--unset", "unsets", multiple=True, metavar="FIELD", help="Remove a field.")
+@click.option(
+    "--label",
+    "label_pairs",
+    multiple=True,
+    metavar="KEY=VALUE",
+    help="Set a label (metadata.labels). Repeat.",
+)
+@click.option("--unlabel", "unlabels", multiple=True, metavar="KEY", help="Remove a label.")
+@click.option(
+    "--annotation",
+    "annotation_pairs",
+    multiple=True,
+    metavar="KEY=VALUE",
+    help="Set an annotation (metadata.annotations). Repeat.",
+)
+@click.option(
+    "--unannotate", "unannotates", multiple=True, metavar="KEY", help="Remove an annotation."
+)
 @click.pass_obj
 def update(
     ctx: CliContext,
@@ -59,6 +77,10 @@ def update(
     removes: tuple[str, ...],
     unsets: tuple[str, ...],
     from_file: str | None,
+    label_pairs: tuple[str, ...],
+    unlabels: tuple[str, ...],
+    annotation_pairs: tuple[str, ...],
+    unannotates: tuple[str, ...],
 ) -> None:
     """Change the fields of the node ADDRESS (``backend:fqtn``) names.
 
@@ -70,6 +92,11 @@ def update(
     field holds; ``--from-file`` replaces each field it names. Relationships carried by
     a reference field can be changed here or with ``kata tax relate``.
 
+    ``--label`` / ``--annotation KEY=VALUE`` set the node's labels and annotations
+    (``metadata``, any kind), checked as ``kata tax create`` checks them; ``--unlabel`` /
+    ``--unannotate KEY`` remove one the node carries. A whole document given to
+    ``--from-file`` sets the labels and annotations it carries too.
+
     Examples:
 
         kata tax update local:payments --set description="Takes payments"
@@ -79,16 +106,35 @@ def update(
         kata tax update local:payments.api --unset environments
 
         kata tax update local:qa --set template_replacements.log_level=debug
+
+        kata tax update local:payments --label cadence=daily --unlabel old --annotation source=x.md
     """
     from katalyst_taxonomy.config.routing import BackendAddressError
     from katalyst_taxonomy.engine.bridge import get_default_registry
-    from katalyst_taxonomy.services.node_update import NodeUpdateService, field_edits
+    from katalyst_taxonomy.services.node_update import (
+        NodeUpdateService,
+        field_edits,
+        metadata_patch,
+    )
 
-    from katalyst_taxonomy_cli.fields import read_spec_file
+    from katalyst_taxonomy_cli.fields import parse_pairs, read_node_file
 
     from .._wiring import resolve_backend
 
-    fragment = read_spec_file(from_file)
+    node_file = read_node_file(from_file)
+    fragment = node_file.spec
+    try:
+        metadata = metadata_patch(
+            labels={**node_file.labels, **parse_pairs(label_pairs, option="--label")},
+            unlabel=unlabels,
+            annotations={
+                **node_file.annotations,
+                **parse_pairs(annotation_pairs, option="--annotation"),
+            },
+            unannotate=unannotates,
+        )
+    except ValueError as exc:
+        raise click.UsageError(str(exc)) from exc
     edits = field_edits(
         set_values=_pairs(sets, "--set"),
         add=_pairs(adds, "--add"),
@@ -104,7 +150,12 @@ def update(
             raise click.ClickException(str(exc)) from exc
 
     outcome = NodeUpdateService(get_default_registry()).update(
-        resolved.backend, resolved.address, edits, fragment=fragment, other_backend=other_backend
+        resolved.backend,
+        resolved.address,
+        edits,
+        fragment=fragment,
+        metadata=metadata,
+        other_backend=other_backend,
     )
     if not outcome.success:
         ctx.output.echo(f"Error: {outcome.error}")