panorama-super-cli 0.2.1__tar.gz → 0.2.3__tar.gz

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/.github/workflows/docs.yml

@@ -23,9 +23,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - name: Install Python
@@ -36,7 +36,7 @@ jobs:
         run: uv run mkdocs build --strict
       - name: Upload Pages artifact
         if: github.ref_type == 'tag'
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: site
 
@@ -49,4 +49,4 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/.github/workflows/lint.yml

@@ -9,9 +9,9 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - name: Install Python
@@ -28,9 +28,9 @@ jobs:
   agents-md-fresh:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - name: Install Python

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/.github/workflows/release.yml

@@ -25,7 +25,7 @@ jobs:
     # no-environment form.
     steps:
       - name: Checkout (full history for changelog notes)
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -40,7 +40,7 @@ jobs:
           echo "Tag $GITHUB_REF_NAME ($GITHUB_SHA) is on main."
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
 

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/.github/workflows/test.yml

@@ -14,9 +14,9 @@ jobs:
         os: [ubuntu-latest, macos-latest]
         python: ["3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - name: Install Python

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/CHANGELOG.md

@@ -7,6 +7,39 @@ project will follow [Semantic Versioning](https://semver.org/). While on
 
 ## [Unreleased]
 
+## v0.2.3 — 2026-06-04
+
+### Added
+
+- **`-of` / `--output-format xml|set` for the offline `--apply --out` artifact.**
+  Mutating commands (`dedup merge`, `name rename`, `name apply`) can now write the
+  rewritten config file as the equivalent PAN-OS `set` script instead of XML.
+  `xml` (the rewritten, `load config`-able config) stays the default, so existing
+  invocations are unchanged; `set` writes the creates/deletes/repoints that
+  achieve the same change, which is easier to read and to paste into a config
+  session or `load config partial`. This is distinct from `-o set`, which renders
+  the dry-run plan to stdout. The blocker hard-gate and repoint-before-delete
+  ordering apply to both formats; a blocked plan writes no file. (#37)
+
+## v0.2.2 — 2026-06-04
+
+### Fixed
+
+- **Repoint-before-delete no longer skipped silently.** A merge or rename whose
+  only safe repoint is a reference the appliers can't express as a flat member
+  rewrite — a NAT source/destination *translation* field, or a rule edit with no
+  rulebase — is now refused with a `blocker` (exit 6) on both the offline and
+  live paths, naming the object and the unmappable referrer. Previously the edit
+  was dropped while the delete/rename still ran, leaving a dangling reference.
+  Advisory unmappable edits with no accompanying teardown still pass with a
+  warning. (#28)
+- **`psc` with no arguments (and unknown commands) print help, not a traceback.**
+  Typer 0.16+ vendors its own Click, so the exceptions the entry point raised
+  were not the `click.*` the wrapper caught and escaped as a traceback ending in
+  `NoArgsIsHelpError`. The wrapper now handles both the vendored and the real
+  Click hierarchies, resolving the module defensively so psc still imports on
+  older Typer. No-args/`--help` exit 0; usage errors exit 2. (#31)
+
 ## v0.2.1 — 2026-06-04
 
 ### Added

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panorama-super-cli
-Version: 0.2.1
+Version: 0.2.3
 Summary: Agent-friendly CLI for Palo Alto Panorama object management: find, dedup/merge, rename, and audit address/service objects safely.
 Project-URL: Homepage, https://github.com/thomaschristory/panorama-super-cli
 Project-URL: Documentation, https://thomaschristory.github.io/panorama-super-cli/

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/docs/guides/output-formats.md

@@ -50,6 +50,25 @@ Member-list edits become `delete` + `set` because PAN-OS `set` on a member field
 can't safely render (NAT translation paths) appear as `# REVIEW` comments; the
 structured (`json`) plan still carries them.
 
+### `-o set` (stdout) vs `--output-format set` (the `--out` file)
+
+These are two different knobs and it's worth keeping them straight:
+
+- **`-o set`** controls what a command prints to **stdout** — use it to read or
+  pipe the plan during a dry-run.
+- **`-of` / `--output-format`** (offline mutating commands only) controls the
+  format of the **`--apply --out` file artifact**: `xml` (default) rewrites the
+  whole config to load with `load config`, while `set` writes the same PAN-OS
+  `set` script shown above to that file — easier to read and to paste into a
+  config session or `load config partial`.
+
+```console
+psc -c panorama.xml dedup merge --keep h-web1 --remove web-primary --apply --out plan.set -of set
+```
+
+`-of` only shapes the file and is ignored without `--apply`; on a live profile
+there is no file artifact, so it has no effect there.
+
 ## Errors
 
 Errors are emitted as a stable JSON envelope:

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/docs/guides/safety.md

@@ -46,6 +46,16 @@ psc -c panorama.xml dedup merge --keep a --remove b --apply --out fixed.xml
 diff <(xmllint --format panorama.xml) <(xmllint --format fixed.xml)
 ```
 
+By default the `--out` file is the rewritten config XML. Pass
+`-of/--output-format set` to instead write the equivalent PAN-OS `set` script
+(the creates/deletes/repoints that achieve the same change) — easier to read and
+to paste into a config session. The blocker gate and repoint-before-delete
+ordering apply to both formats identically; a blocked plan writes no file.
+
+```console
+psc -c panorama.xml dedup merge --keep a --remove b --apply --out plan.set -of set
+```
+
 ## Live writes
 
 Live `--apply` pushes the plan to Panorama's **candidate** config over the XML

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/docs/reference/cli.md

@@ -17,9 +17,11 @@ These are **context** options — pass them *before* the subcommand:
 | `--debug` | Verbose structured logs on stderr. |
 | `--version` | Print version and exit. |
 
-Write-execution options (`--apply`, `--out`) belong to the individual mutating
-commands and are passed *after* the command. `--apply` is the only path to a
-write; offline it requires `--out PATH` (a new file), while live it pushes to
+Write-execution options (`--apply`, `--out`, `-of/--output-format`) belong to
+the individual mutating commands and are passed *after* the command. `--apply`
+is the only path to a write; offline it requires `--out PATH` (a new file) and
+`-of xml|set` chooses what that file holds (default `xml`), while live it pushes
+to
 Panorama's candidate config and never commits. See
 [Writes and safety](../guides/safety.md).
 
@@ -42,7 +44,7 @@ psc dedup addresses
 psc dedup services
 psc dedup merge --keep NAME --remove NAME [--location LOC]
                [--keep-location LOC] [--remove-location LOC]
-               [--allow-value-change] [--apply] [--out PATH]
+               [--allow-value-change] [--apply] [--out PATH] [-of xml|set]
 ```
 
 Find duplicates; merge one object into another, repointing all references. See
@@ -63,8 +65,8 @@ Where-used, recursive unused, and dangling-reference audit. See
 
 ```
 psc name lint [--all]
-psc name rename --object OLD --to NEW [--kind KIND] [--location LOC] [--apply] [--out PATH]
-psc name apply  --object NAME            [--location LOC] [--apply] [--out PATH]
+psc name rename --object OLD --to NEW [--kind KIND] [--location LOC] [--apply] [--out PATH] [-of xml|set]
+psc name apply  --object NAME            [--location LOC] [--apply] [--out PATH] [-of xml|set]
 ```
 
 Opt-in naming-template lint and reference-aware rename. See

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/psc/_version.py

@@ -4,4 +4,4 @@
 Keep this in sync with `[project].version` in `pyproject.toml`.
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/psc/cli/_plan.py

@@ -7,14 +7,39 @@ refused, dry-run is the default, and `--apply` is the only path to a write.
 
 from __future__ import annotations
 
+import typer
+
 from psc.cli.runtime import Runtime
 from psc.core.changeset import ChangeSet
 from psc.core.setcmd import render_changeset
+from psc.core.source import ConfigFormat
 from psc.output.errors import ErrorType, PscError
 from psc.output.format import OutputFormat, render
 
+# Shared across every mutating command so the `--out` artifact toggle reads and
+# behaves identically wherever `complete()` is used (dedup merge, name rename,
+# name apply). Default `xml` keeps existing scripts byte-for-byte compatible.
+OUT_FORMAT_OPTION = typer.Option(
+    ConfigFormat.XML,
+    "--output-format",
+    "-of",
+    help=(
+        "Format of the offline --out artifact. 'xml' (default) rewrites the whole "
+        "config to load with `load config`; 'set' writes the equivalent PAN-OS set "
+        "script (the creates/deletes/repoints) — easier to read and to paste into a "
+        "config session. Only affects --out; ignored without --apply."
+    ),
+)
+
 
-def complete(rt: Runtime, cs: ChangeSet, *, apply: bool, out_path: str | None) -> None:
+def complete(
+    rt: Runtime,
+    cs: ChangeSet,
+    *,
+    apply: bool,
+    out_path: str | None,
+    out_format: ConfigFormat = ConfigFormat.XML,
+) -> None:
     """Render `cs` in the chosen format, then apply it iff `apply`.
 
     A blocked plan raises `CONFLICT` (exit 6) before any write. The structured
@@ -43,7 +68,7 @@ def complete(rt: Runtime, cs: ChangeSet, *, apply: bool, out_path: str | None) -
         return
 
     if apply:
-        result = rt.source().apply(cs, out_path=out_path)
+        result = rt.source().apply(cs, out_path=out_path, out_format=out_format)
         rt.stderr.print(
             f"[green]applied[/green] {result.ops} operation(s)"
             + (f" → {result.out_path}" if result.out_path else "")

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/psc/cli/app.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+from types import ModuleType
 
 import click
 import typer
@@ -15,6 +16,28 @@ from psc.config.loader import load_config
 from psc.output.errors import PscError
 from psc.output.format import OutputFormat
 
+
+def _click_exception_module() -> ModuleType:
+    """The Click `exceptions` module whose flavour matches what `app(...)` raises.
+
+    Typer >=0.16 vendors its own Click under `typer._click`, so the exceptions
+    `app(standalone_mode=False)` raises are not subclasses of the real `click.*`
+    (issue #31). Older Typer has no `typer._click` at all — importing it at
+    module top level would crash psc on *import*, breaking every command, which
+    is strictly worse than the bug we're fixing. Resolve defensively: prefer the
+    vendored module, fall back to the real Click (which older Typer raises).
+    """
+    try:
+        from typer._click import exceptions as vendored  # noqa: PLC0415 — conditional
+    except ImportError:
+        from click import exceptions as real  # noqa: PLC0415 — fallback for older Typer
+
+        return real
+    return vendored
+
+
+_typer_click_exc = _click_exception_module()
+
 app = typer.Typer(
     add_completion=True,
     no_args_is_help=True,
@@ -125,18 +148,27 @@ def _emit_error(err: PscError) -> None:
 
 
 def main() -> None:
+    # Typer 0.26 vendors its own Click (`typer._click`), so the exceptions
+    # `app(standalone_mode=False)` raises are NOT subclasses of the real
+    # `click.*`. Catch both flavours, or a no-args/`--help`/bad-command run
+    # escapes uncaught and prints a traceback instead of help (#31).
     try:
         app(standalone_mode=False)
     except PscError as err:
         _emit_error(err)
         raise SystemExit(err.exit_code) from None
-    except click.UsageError as err:
-        err.show()
-        raise SystemExit(2) from None
-    except (click.exceptions.Abort, KeyboardInterrupt):
+    except (KeyboardInterrupt, click.exceptions.Abort, _typer_click_exc.Abort):
         Console(stderr=True).print("aborted")
         raise SystemExit(130) from None
-    except click.exceptions.Exit as err:
+    except (click.exceptions.Exit, _typer_click_exc.Exit) as err:
+        raise SystemExit(err.exit_code) from None
+    except (click.ClickException, _typer_click_exc.ClickException) as err:
+        # `no_args_is_help` (and `--help`) already printed the help text; the
+        # raise is just a stop signal, so exit 0 rather than rendering it as an
+        # error. Genuine usage errors still print and exit non-zero.
+        if err.__class__.__name__ == "NoArgsIsHelpError":
+            raise SystemExit(0) from None
+        err.show()
         raise SystemExit(err.exit_code) from None
 
 

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/psc/cli/dedup_cmds.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import typer
 
-from psc.cli._plan import complete
+from psc.cli._plan import OUT_FORMAT_OPTION, complete
 from psc.cli.runtime import Runtime
 from psc.core.dedup import (
     DuplicateGroup,
@@ -14,6 +14,7 @@ from psc.core.dedup import (
     plan_merge,
 )
 from psc.core.refs import ReferenceGraph
+from psc.core.source import ConfigFormat
 from psc.output.errors import ErrorType, PscError
 from psc.output.format import render
 
@@ -71,8 +72,9 @@ def merge(
     ),
     apply: bool = typer.Option(False, "--apply", help="Execute the merge (default: dry-run)."),
     out: str | None = typer.Option(
-        None, "--out", help="Offline: write the rewritten config XML here."
+        None, "--out", help="Offline: write the rewritten config here (see --output-format)."
     ),
+    output_format: ConfigFormat = OUT_FORMAT_OPTION,
 ) -> None:
     """Collapse one address object into another, repointing every reference.
 
@@ -91,4 +93,4 @@ def merge(
         drop=ObjectRef(name=remove, location=remove_location or default_loc),
         allow_value_change=allow_value_change,
     )
-    complete(rt, cs, apply=apply, out_path=out)
+    complete(rt, cs, apply=apply, out_path=out, out_format=output_format)

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/psc/cli/name_cmds.py

@@ -4,12 +4,13 @@ from __future__ import annotations
 
 import typer
 
-from psc.cli._plan import complete
+from psc.cli._plan import OUT_FORMAT_OPTION, complete
 from psc.cli.runtime import Runtime
 from psc.core.changeset import ObjectKind
 from psc.core.naming import lint as lint_engine
 from psc.core.naming import plan_rename
 from psc.core.refs import ReferenceGraph
+from psc.core.source import ConfigFormat
 from psc.output.errors import ErrorType, PscError
 from psc.output.format import render
 
@@ -49,7 +50,10 @@ def rename(
     kind: ObjectKind = typer.Option(ObjectKind.ADDRESS, "--kind"),
     location: str | None = typer.Option(None, "--location"),
     apply: bool = typer.Option(False, "--apply", help="Execute the rename (default: dry-run)."),
-    out: str | None = typer.Option(None, "--out", help="Offline: write rewritten config XML here."),
+    out: str | None = typer.Option(
+        None, "--out", help="Offline: write rewritten config here (see --output-format)."
+    ),
+    output_format: ConfigFormat = OUT_FORMAT_OPTION,
 ) -> None:
     """Rename one object, repointing every reference (refuses on shadow collisions)."""
     rt: Runtime = ctx.obj
@@ -57,7 +61,7 @@ def rename(
     snap = rt.snapshot()
     graph = ReferenceGraph.build(snap)
     cs = plan_rename(snap, graph, kind=kind, location_name=loc, old_name=object_name, new_name=to)
-    complete(rt, cs, apply=apply, out_path=out)
+    complete(rt, cs, apply=apply, out_path=out, out_format=output_format)
 
 
 @app.command("apply")
@@ -66,7 +70,10 @@ def apply_scheme(
     object_name: str = typer.Option(..., "--object", help="Object to rename to its scheme name."),
     location: str | None = typer.Option(None, "--location"),
     apply: bool = typer.Option(False, "--apply", help="Execute the rename (default: dry-run)."),
-    out: str | None = typer.Option(None, "--out", help="Offline: write rewritten config XML here."),
+    out: str | None = typer.Option(
+        None, "--out", help="Offline: write rewritten config here (see --output-format)."
+    ),
+    output_format: ConfigFormat = OUT_FORMAT_OPTION,
 ) -> None:
     """Rename one object to the name the configured scheme implies for its value."""
     rt: Runtime = ctx.obj
@@ -98,4 +105,4 @@ def apply_scheme(
     cs = plan_rename(
         snap, graph, kind=kind, location_name=loc, old_name=object_name, new_name=suggested
     )
-    complete(rt, cs, apply=apply, out_path=out)
+    complete(rt, cs, apply=apply, out_path=out, out_format=output_format)

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/psc/core/changeset.py

@@ -125,3 +125,56 @@ class ChangeSet(BaseModel):
         out += [r.summary for r in self.renames]
         out += [d.summary for d in self.deletes]
         return out
+
+
+def reference_edit_is_mappable(edit: ReferenceEdit) -> bool:
+    """Whether both appliers can express `edit` as a flat member-field rewrite.
+
+    The single source of truth behind `apply_xml._referrer_field_element` and
+    `apply_live._referrer_field_xpath`: a member field they know how to address
+    (a group's `static`/`members`, a security-rule field, a NAT src/dst list).
+    A NAT *translation* field is nested with no flat list, and a rule edit with
+    no `rulebase` can't be located — both are unmappable, and an applier silently
+    skips them. The planner uses this to refuse such a skip when the same plan
+    tears the target down, instead of leaving a dangling reference (#28).
+    """
+    kind = edit.referrer_kind
+    if kind in ("address-group", "service-group"):
+        return True
+    if kind == "security-rule":
+        return edit.rulebase is not None
+    if kind == "nat-rule":
+        return edit.rulebase is not None and edit.field in ("source", "destination")
+    return False
+
+
+def gate_unmappable_reference_edits(cs: ChangeSet) -> None:
+    """Promote unsafe unmappable reference edits to blockers, in place.
+
+    An unmappable edit (see `reference_edit_is_mappable`) is silently skipped at
+    apply time. If the plan also deletes or renames an object, that skip drops
+    the repoint that kept the teardown safe — a dangling reference, the exact
+    failure repoint-before-delete exists to prevent. Make it a hard blocker. With
+    no teardown the edit is advisory only, so it stays a warning.
+
+    Clearing the ops is the planner's job (a blocked plan carries zero ops); this
+    only classifies.
+    """
+    unmappable = [e for e in cs.reference_edits if not reference_edit_is_mappable(e)]
+    if not unmappable:
+        return
+    torn_down = [d.name for d in cs.deletes] + [r.old_name for r in cs.renames]
+    for e in unmappable:
+        referrer = f"{e.referrer_kind} '{e.referrer_name}'@{e.referrer_location} {e.field}"
+        if torn_down:
+            targets = ", ".join(f"'{t}'" for t in torn_down)
+            cs.blockers.append(
+                f"cannot repoint {referrer} automatically (no flat member list to rewrite); "
+                f"removing/renaming {targets} would leave a dangling reference — edit that "
+                "field manually, then re-run"
+            )
+        else:
+            cs.warnings.append(
+                f"{referrer} can't be repointed automatically (no flat member list); "
+                "review and edit it by hand"
+            )

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/psc/core/dedup.py

@@ -14,7 +14,13 @@ from __future__ import annotations
 
 from pydantic import BaseModel, Field
 
-from psc.core.changeset import ChangeSet, ObjectDelete, ObjectKind, ReferenceEdit
+from psc.core.changeset import (
+    ChangeSet,
+    ObjectDelete,
+    ObjectKind,
+    ReferenceEdit,
+    gate_unmappable_reference_edits,
+)
 from psc.core.models import Location, Snapshot
 from psc.core.normalize import normalize_address, service_key
 from psc.core.refs import Reference, ReferenceGraph
@@ -155,23 +161,18 @@ def plan_merge(
             cs.warnings.append(
                 f"{ref.referrer_kind} '{ref.referrer_name}' {ref.field} would be emptied"
             )
-        if ref.field in ("source-translation", "destination-translation"):
-            # psc cannot safely rewrite NAT translation fields offline (the XML
-            # path is nested and renderer-flagged), so deleting `drop` would
-            # leave a dangling translation reference. Refuse rather than warn.
-            cs.blockers.append(
-                f"NAT rule '{ref.referrer_name}' references '{drop.name}' in "
-                f"{ref.field}; psc can't safely rewrite NAT translation offline — "
-                "edit that field manually, then re-run the merge"
-            )
+
+    cs.deletes.append(ObjectDelete(kind=ObjectKind.ADDRESS, name=drop.name, location=drop.location))
+    # Refuse any repoint the appliers would silently skip (e.g. a NAT translation
+    # field) now that the delete is in the plan — a skipped repoint + delete is a
+    # dangling reference. Mirrors `plan_rename`; offline and live share the gate.
+    gate_unmappable_reference_edits(cs)
 
     if cs.blockers:
         # Invariant: a blocked plan carries zero ops, so no consumer can execute
         # a partial rewrite by iterating ops without checking `is_blocked`.
         cs.reference_edits.clear()
-        return cs
-
-    cs.deletes.append(ObjectDelete(kind=ObjectKind.ADDRESS, name=drop.name, location=drop.location))
+        cs.deletes.clear()
     return cs
 
 

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/psc/core/naming.py

@@ -15,7 +15,13 @@ import re
 
 from pydantic import BaseModel
 
-from psc.core.changeset import ChangeSet, ObjectKind, ObjectRename, ReferenceEdit
+from psc.core.changeset import (
+    ChangeSet,
+    ObjectKind,
+    ObjectRename,
+    ReferenceEdit,
+    gate_unmappable_reference_edits,
+)
 from psc.core.dedup import field_members
 from psc.core.models import Address, AddressType, Location, Service, Snapshot
 from psc.core.refs import ReferenceGraph
@@ -182,4 +188,12 @@ def plan_rename(
     cs.renames.append(
         ObjectRename(kind=kind, location=location_name, old_name=old_name, new_name=new_name)
     )
+    # Refuse any repoint the appliers would silently skip (e.g. a NAT translation
+    # field): skipping it while renaming the object away leaves a dangling
+    # reference. Shared gate keeps offline and live identical (#28).
+    gate_unmappable_reference_edits(cs)
+    if cs.blockers:
+        # Invariant: a blocked plan carries zero ops (see `plan_merge`).
+        cs.reference_edits.clear()
+        cs.renames.clear()
     return cs

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/psc/core/source.py

@@ -18,6 +18,7 @@ Writes are deliberately conservative:
 from __future__ import annotations
 
 import ssl
+from enum import Enum
 from pathlib import Path
 
 from pydantic import BaseModel, Field
@@ -26,9 +27,23 @@ from psc.core.apply_xml import apply_changeset
 from psc.core.changeset import ChangeSet
 from psc.core.models import Snapshot
 from psc.core.parse import parse_config
+from psc.core.setcmd import render_changeset
 from psc.output.errors import ErrorType, PscError
 
 
+class ConfigFormat(str, Enum):
+    """Format of the artifact an offline `apply` writes to `--out`.
+
+    `xml` rewrites the whole exported config (loadable with `load config`);
+    `set` emits the equivalent PAN-OS `set` script (the creations/deletes/
+    repoints that achieve the same change) — easier to read and to paste into a
+    config session or `load config partial`.
+    """
+
+    XML = "xml"
+    SET = "set"
+
+
 class ApplyResult(BaseModel):
     applied: bool
     ops: int
@@ -83,7 +98,13 @@ class OfflineSource:
         except Exception as exc:
             raise PscError(f"failed to parse {self.path}: {exc}", ErrorType.INPUT) from exc
 
-    def apply(self, cs: ChangeSet, *, out_path: str | Path | None) -> ApplyResult:
+    def apply(
+        self,
+        cs: ChangeSet,
+        *,
+        out_path: str | Path | None,
+        out_format: ConfigFormat = ConfigFormat.XML,
+    ) -> ApplyResult:
         if out_path is None:
             raise PscError(
                 "offline apply needs --out PATH (the rewritten config is never "
@@ -93,6 +114,20 @@ class OfflineSource:
         out = Path(out_path)
         if out.resolve() == self.path.resolve():
             raise PscError("--out must differ from the source config path", ErrorType.CONFIG)
+        # The blocker gate is enforced here for *every* format — the XML path
+        # relies on `apply_changeset`, but the set path renders the plan without
+        # it, so refuse before writing rather than emit a `# BLOCKED` file.
+        if cs.is_blocked:
+            raise PscError(
+                "refusing to apply a blocked plan",
+                ErrorType.CONFLICT,
+                details={"blockers": cs.blockers},
+            )
+        # Both artifacts share the same safety guards above; only the bytes differ.
+        if out_format is ConfigFormat.SET:
+            script = render_changeset(cs)
+            out.write_text("\n".join(script) + "\n", encoding="utf-8")
+            return ApplyResult(applied=True, ops=cs.op_count, out_path=str(out), set_script=script)
         new_xml = apply_changeset(self._xml, cs)
         out.write_text(new_xml, encoding="utf-8")
         return ApplyResult(applied=True, ops=cs.op_count, out_path=str(out))
@@ -221,9 +256,19 @@ class LiveSource:
     def snapshot(self) -> Snapshot:
         return parse_config(self.raw_xml())
 
-    def apply(self, cs: ChangeSet, *, out_path: str | Path | None) -> ApplyResult:
+    def apply(
+        self,
+        cs: ChangeSet,
+        *,
+        out_path: str | Path | None,
+        out_format: ConfigFormat = ConfigFormat.XML,
+    ) -> ApplyResult:
         """Push `cs` to Panorama's candidate config over the XML API.
 
+        `out_path`/`out_format` are accepted for interface parity with the
+        offline source but ignored — a live apply leaves a candidate on the
+        device, not a file, so there is no artifact to format.
+
         The plan is lowered to xpath set/edit/delete/rename ops and replayed in
         order (repoint before delete). The `blockers` gate and name-addressing
         check run *before* any device contact, so a refused plan never writes.

{panorama_super_cli-0.2.1 → panorama_super_cli-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "panorama-super-cli"
-version = "0.2.1"
+version = "0.2.3"
 description = "Agent-friendly CLI for Palo Alto Panorama object management: find, dedup/merge, rename, and audit address/service objects safely."
 readme = "README.md"
 requires-python = ">=3.12"