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

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

@@ -7,6 +7,20 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panorama-super-cli
-Version: 0.2.2
+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.2 → 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.2 → 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.2 → 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.2 → 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.2"
+__version__ = "0.2.3"

{panorama_super_cli-0.2.2 → 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.2 → 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.2 → 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.2 → 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.2 → panorama_super_cli-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "panorama-super-cli"
-version = "0.2.2"
+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"

{panorama_super_cli-0.2.2 → panorama_super_cli-0.2.3}/skills/panorama-super-cli/SKILL.md

@@ -29,7 +29,8 @@ psc [GLOBAL OPTS] <group> <command> [ARGS] [WRITE OPTS]
 - **Global (context) options go *before* the group:** `-c/--config FILE`,
   `-p/--profile NAME`, `-o/--output FMT`, `-d/--device-group NAME`, `--strict`,
   `--debug`.
-- **Write-execution options go *after* the command:** `--apply`, `--out PATH`.
+- **Write-execution options go *after* the command:** `--apply`, `--out PATH`,
+  `-of/--output-format xml|set`.
 
 ```bash
 psc -c panorama.xml -o json find ip 10.0.0.10
@@ -39,7 +40,20 @@ psc -c panorama.xml dedup merge --keep h-web1 --remove web-primary --apply --out
 ## Pick a source
 
 - **Offline:** `-c panorama.xml` — an exported config. Read-only against the
-  device; `--apply` writes a *new* file via `--out`.
+  device; `--apply` writes a *new* file via `--out` (it never overwrites the
+  source export). Choose what that file holds with `-of/--output-format`:
+  - `xml` (default) — the whole config rewritten, loadable with `load config`.
+  - `set` — just the equivalent PAN-OS `set` script (the creates/deletes/
+    repoints that achieve the change). Easier to read and to paste into a
+    config session or `load config partial`. Use this when a human reviews the
+    change or you want a minimal, diff-like artifact; use `xml` when you need a
+    full, directly-loadable replacement config.
+
+  ```bash
+  psc -c cfg.xml dedup merge --keep a --remove b --apply --out plan.set -of set
+  ```
+  (`-of` only shapes the `--out` file; for the script on stdout in a dry-run,
+  use `-o set` instead.)
 - **Live:** `-p prod` — fetches the running config over the XML API. `--apply`
   (no `--out`) pushes the plan to Panorama's **candidate** config and never
   commits; you review and commit yourself.

{panorama_super_cli-0.2.2 → panorama_super_cli-0.2.3}/tests/test_cli.py

@@ -122,6 +122,51 @@ def test_merge_apply_writes_out(tmp_path: Path) -> None:
     assert "web-primary" not in out.read_text(encoding="utf-8")
 
 
+def test_merge_apply_out_set_writes_set_script(tmp_path: Path) -> None:
+    out = tmp_path / "fixed.set"
+    cp = run(
+        "-c",
+        str(FIXTURE),
+        "dedup",
+        "merge",
+        "--keep",
+        "h-web1",
+        "--remove",
+        "web-primary",
+        "--apply",
+        "--out",
+        str(out),
+        "-of",
+        "set",
+    )
+    assert cp.returncode == 0
+    assert out.exists()
+    text = out.read_text(encoding="utf-8")
+    assert "delete shared address web-primary" in text
+    assert "<entry" not in text  # the --out artifact is a set script, not XML
+
+
+def test_merge_apply_out_xml_is_default(tmp_path: Path) -> None:
+    out = tmp_path / "fixed.xml"
+    cp = run(
+        "-c",
+        str(FIXTURE),
+        "dedup",
+        "merge",
+        "--keep",
+        "h-web1",
+        "--remove",
+        "web-primary",
+        "--apply",
+        "--out",
+        str(out),
+        "--output-format",
+        "xml",
+    )
+    assert cp.returncode == 0
+    assert "web-primary" not in out.read_text(encoding="utf-8")  # rewritten XML, object gone
+
+
 def test_no_source_errors_config() -> None:
     cp = run("-o", "json", "find", "ip", "10.0.0.10")
     assert cp.returncode == 9

panorama_super_cli-0.2.3/tests/test_source.py

@@ -0,0 +1,62 @@
+"""Offline `apply` artifact-format behaviour (#37: write `set` script instead of XML)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from psc.core.changeset import ChangeSet, ObjectDelete, ObjectKind
+from psc.core.source import ConfigFormat, OfflineSource
+from psc.output.errors import PscError
+
+FIXTURE = Path(__file__).parent / "fixtures" / "panorama-config.xml"
+
+
+def _delete_cs() -> ChangeSet:
+    return ChangeSet(
+        title="t",
+        deletes=[ObjectDelete(kind=ObjectKind.ADDRESS, name="web-primary", location="shared")],
+    )
+
+
+def test_apply_set_format_writes_set_script_not_xml(tmp_path: Path) -> None:
+    out = tmp_path / "plan.set"
+    res = OfflineSource(FIXTURE).apply(_delete_cs(), out_path=out, out_format=ConfigFormat.SET)
+    text = out.read_text(encoding="utf-8")
+    assert "delete shared address web-primary" in text
+    assert "<entry" not in text  # the artifact is a set script, never XML
+    assert res.set_script  # the rendered lines ride back on the result
+    assert res.out_path == str(out)
+
+
+def test_apply_xml_format_is_the_default(tmp_path: Path) -> None:
+    out = tmp_path / "fixed.xml"
+    res = OfflineSource(FIXTURE).apply(_delete_cs(), out_path=out)
+    text = out.read_text(encoding="utf-8")
+    assert "<" in text  # still rewritten XML when no format is asked for
+    assert not res.set_script
+
+
+def test_apply_set_format_still_refuses_overwriting_source() -> None:
+    with pytest.raises(PscError):
+        OfflineSource(FIXTURE).apply(_delete_cs(), out_path=FIXTURE, out_format=ConfigFormat.SET)
+
+
+def test_apply_set_format_still_requires_out_path() -> None:
+    with pytest.raises(PscError):
+        OfflineSource(FIXTURE).apply(_delete_cs(), out_path=None, out_format=ConfigFormat.SET)
+
+
+def test_apply_set_format_refuses_blocked_plan_and_writes_nothing(tmp_path: Path) -> None:
+    # The blocker gate is enforced at the applier level for every format, not
+    # only in the CLI — a blocked plan must never reach a written artifact.
+    out = tmp_path / "plan.set"
+    blocked = ChangeSet(
+        title="t",
+        blockers=["cross-scope reference can't be repointed"],
+        deletes=[ObjectDelete(kind=ObjectKind.ADDRESS, name="web-primary", location="shared")],
+    )
+    with pytest.raises(PscError):
+        OfflineSource(FIXTURE).apply(blocked, out_path=out, out_format=ConfigFormat.SET)
+    assert not out.exists()