fix(import,export): scope-aware writes, refuse dangerous categories by default

mythy import used to write every key the YAML mentioned as long as
the catalog didn't mark it READONLY="YES". That meant a hand-edited
YAML carrying e.g. CodeNum or EnableBoard_* could put a fielded
protection relay into a FATALE state requiring SET_DB_DEFAULT and a
physical power-cycle. Catalog markers exist to flag these cases but
mythy was ignoring them outside of READONLY.

Add two layers of scope filtering on writes, both gated on
locale-independent catalog attributes:

  - SKIP="YES" — identification / IP / comm config. Writing any of
    these over the live Modbus connection typically drops the
    connection mid-transaction. Excluded by default; --include-skip
    plus --yes-i-understand to opt in.
  - VISIBILITY="3" — Administrator / Menu Riservato subtree, plus
    DATA-level overrides like CodeNum. Cascades from the containing
    group AND honored on the DATA element itself. Excluded by default;
    --include-hidden plus --yes-i-understand.
  - --all is shorthand for both opt-ins; READONLY="YES" stays a hard
    mythy-side refuse (the device empirically does not enforce
    read-only on the wire, so this defensive guard remains load-
    bearing).

Path-based per-category opt-ins (--include-ntp, etc.) from the
original spec are dropped: top-level menu names are locale-dependent
(`Network Services` in us vs `Comandi` in it), and the catalog
attributes give a strictly better classification anyway. See the
design note pinned to the issue for the full reasoning.

Banner + abort: when an --include-* flag is set without
--yes-i-understand, the command prints the affected keys grouped by
reason and refuses to proceed. With --yes-i-understand the same
grouped banner prints before the writes hit the device, so even in
the CI case the operator has accountability output.

Export gains the symmetric flag set: --include-skip is new; --all is
new; --include-readonly/--include-hidden already existed. No
confirmation gate on export — it's read-only.

Closes #8

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ale-rinaldi

README.md

@@ -238,8 +238,18 @@ mythy import --host 192.0.2.10 sample.yaml
 # Different product → pass --force to skip the product-mismatch check.
 ```
 
-Read-only, hidden, and module-disabled DATA are excluded by default;
-`--include-readonly` and `--include-hidden` widen the export.
+Read-only, hidden, `SKIP="YES"`, and module-disabled DATA are excluded
+by default. `--include-readonly`, `--include-hidden`, and
+`--include-skip` widen the export; `--all` is shorthand for all three.
+
+`mythy import` mirrors the same flags. By default it refuses to write
+`SKIP="YES"` (identification, IP/comm config — writing these usually
+drops the live connection) or `VISIBILITY="3"` keys (the Administrator
+subtree — wrong values there can leave the device in a state
+requiring a factory reset). To opt in, set the matching `--include-*`
+flag AND `--yes-i-understand`; `--all` is the shortcut for both
+opt-ins together. Without `--yes-i-understand`, the command prints a
+banner of the keys that would be touched and aborts.
 
 ### Raw escape hatches
 

cmd/mythy/export.go

@@ -13,7 +13,7 @@ import (
 func newExportCmd(cf *catalogFlags) *cobra.Command {
 	var conn connFlags
 	var scope string
-	var includeHidden, includeReadOnly, noProgress bool
+	var includeHidden, includeReadOnly, includeSkip, includeAll, noProgress bool
 
 	cmd := &cobra.Command{
 		Use:   "export <file>",
@@ -32,11 +32,17 @@ func newExportCmd(cf *catalogFlags) *cobra.Command {
 				progress = makeReadProgress(cmd.ErrOrStderr(), false)
 			}
 
+			if includeAll {
+				includeHidden = true
+				includeReadOnly = true
+				includeSkip = true
+			}
 			b, err := configio.Export(ctx, s, configio.ExportOptions{
 				Scope: scope,
 				Filter: session.ExportFilter{
 					IncludeHidden:   includeHidden,
 					IncludeReadOnly: includeReadOnly,
+					IncludeSkip:     includeSkip,
 				},
 				Progress: progress,
 			})
@@ -54,6 +60,8 @@ func newExportCmd(cf *catalogFlags) *cobra.Command {
 	cmd.Flags().StringVar(&scope, "scope", "", "menu path to export (default: whole device)")
 	cmd.Flags().BoolVar(&includeHidden, "include-hidden", false, "include VISIBILITY=3 (Administrator) groups")
 	cmd.Flags().BoolVar(&includeReadOnly, "include-readonly", false, "include READONLY=YES entries")
+	cmd.Flags().BoolVar(&includeSkip, "include-skip", false, "include SKIP=YES entries (identification, IP/comm config)")
+	cmd.Flags().BoolVar(&includeAll, "all", false, "shorthand for --include-hidden --include-readonly --include-skip")
 	cmd.Flags().BoolVar(&noProgress, "no-progress", false, "suppress the progress indicator (auto-suppressed when stderr isn't a TTY)")
 	return cmd
 }

cmd/mythy/import.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io"
 	"os"
 
 	"github.com/gridsociety/mythy/pkg/configio"
@@ -13,6 +14,7 @@ import (
 func newImportCmd(cf *catalogFlags) *cobra.Command {
 	var conn connFlags
 	var dryRun, force, noProgress bool
+	var includeSkip, includeHidden, includeAll, yesIUnderstand bool
 	var format string
 
 	cmd := &cobra.Command{
@@ -48,35 +50,119 @@ func newImportCmd(cf *catalogFlags) *cobra.Command {
 			if !noProgress {
 				progress = makeReadProgress(cmd.ErrOrStderr(), false)
 			}
-			applyOpts := configio.ApplyOptions{Progress: progress}
+			optIns := resolveScopeOptIns(includeSkip, includeHidden, includeAll)
+			applyOpts := configio.ApplyOptions{
+				Progress:      progress,
+				IncludeSkip:   optIns.skip,
+				IncludeHidden: optIns.hidden,
+			}
 
 			out := cmd.OutOrStdout()
+
+			// Opt-in without --yes-i-understand → pre-flight dry-run to
+			// surface exactly which keys would be touched in each opted-
+			// in category, then refuse to proceed. The Diff cost is only
+			// paid in this safety path; the no-opt-in default flow goes
+			// straight to Apply with one Diff pass.
+			if optIns.anyRequested() && !yesIUnderstand {
+				report, err := configio.ApplyDryRun(ctx, s, parsed, applyOpts)
+				if err != nil {
+					return err
+				}
+				printOptInBanner(out, report, optIns, "would write (rerun with --yes-i-understand to proceed)")
+				return errors.New("scope opt-in requires --yes-i-understand to proceed")
+			}
+
 			if dryRun {
 				report, err := configio.ApplyDryRun(ctx, s, parsed, applyOpts)
 				if err != nil {
 					return err
 				}
-				fmt.Fprintf(out, "would write %d key(s): %v\n", len(report.WouldApply), report.WouldApply)
-				if len(report.Skipped) > 0 {
-					fmt.Fprintf(out, "would skip %d READONLY key(s): %v\n", len(report.Skipped), report.Skipped)
+				if optIns.anyRequested() {
+					printOptInBanner(out, report, optIns, "would write")
 				}
+				printDryRun(out, report, optIns)
 				return nil
 			}
+
 			report, err := configio.Apply(ctx, s, parsed, applyOpts)
 			if err != nil {
 				return err
 			}
-			fmt.Fprintf(out, "wrote %d key(s): %v\n", len(report.Applied), report.Applied)
-			if len(report.Skipped) > 0 {
-				fmt.Fprintf(out, "skipped %d READONLY key(s) the file changed: %v\n", len(report.Skipped), report.Skipped)
+			if optIns.anyRequested() {
+				printOptInBanner(out, report, optIns, "WRITING")
 			}
+			fmt.Fprintf(out, "wrote %d key(s): %v\n", len(report.Applied), report.Applied)
+			printSkipSummary(out, report, optIns)
 			return nil
 		},
 	}
 	conn.bind(cmd)
 	cmd.Flags().BoolVar(&dryRun, "dry-run", false, "show what would change; perform no writes")
 	cmd.Flags().BoolVar(&force, "force", false, "skip the product-mismatch check")
 	cmd.Flags().BoolVar(&noProgress, "no-progress", false, "suppress the progress indicator (auto-suppressed when stderr isn't a TTY)")
+	cmd.Flags().BoolVar(&includeSkip, "include-skip", false, "allow writes to SKIP=YES keys (identification, IP/comm config)")
+	cmd.Flags().BoolVar(&includeHidden, "include-hidden", false, "allow writes to VISIBILITY=3 keys (Administrator subtree)")
+	cmd.Flags().BoolVar(&includeAll, "all", false, "shorthand for --include-skip --include-hidden")
+	cmd.Flags().BoolVar(&yesIUnderstand, "yes-i-understand", false, "confirm intent when an --include-* flag is set")
 	cmd.Flags().StringVar(&format, "format", "", "human|json|yaml (default: from MYTHY_FORMAT)")
 	return cmd
 }
+
+type scopeOptIns struct {
+	skip   bool
+	hidden bool
+}
+
+func (s scopeOptIns) anyRequested() bool { return s.skip || s.hidden }
+
+func resolveScopeOptIns(skip, hidden, all bool) scopeOptIns {
+	if all {
+		return scopeOptIns{skip: true, hidden: true}
+	}
+	return scopeOptIns{skip: skip, hidden: hidden}
+}
+
+// printOptInBanner lists keys that fall under an opt-in flag, grouped
+// by reason. Called for both the abort path (no --yes-i-understand)
+// and the proceed path (with --yes-i-understand) so the operator
+// always sees the full list before writes hit the device.
+func printOptInBanner(out io.Writer, rep *configio.Report, optIns scopeOptIns, label string) {
+	if optIns.skip && len(rep.InSkipCategory) > 0 {
+		fmt.Fprintf(out, "%s %d connection-disruptive key(s) (SKIP=YES — identification, IP/comm config): %v\n",
+			label, len(rep.InSkipCategory), rep.InSkipCategory)
+	}
+	if optIns.hidden && len(rep.InHiddenCategory) > 0 {
+		fmt.Fprintf(out, "%s %d hidden key(s) (VISIBILITY=3 — Administrator subtree): %v\n",
+			label, len(rep.InHiddenCategory), rep.InHiddenCategory)
+	}
+}
+
+func printDryRun(out io.Writer, rep *configio.Report, optIns scopeOptIns) {
+	fmt.Fprintf(out, "would write %d key(s): %v\n", len(rep.WouldApply), rep.WouldApply)
+	if len(rep.Skipped) > 0 {
+		fmt.Fprintf(out, "would skip %d READONLY key(s): %v\n", len(rep.Skipped), rep.Skipped)
+	}
+	if !optIns.skip && len(rep.InSkipCategory) > 0 {
+		fmt.Fprintf(out, "would skip %d SKIP key(s) (use --include-skip to write): %v\n",
+			len(rep.InSkipCategory), rep.InSkipCategory)
+	}
+	if !optIns.hidden && len(rep.InHiddenCategory) > 0 {
+		fmt.Fprintf(out, "would skip %d hidden key(s) (use --include-hidden to write): %v\n",
+			len(rep.InHiddenCategory), rep.InHiddenCategory)
+	}
+}
+
+func printSkipSummary(out io.Writer, rep *configio.Report, optIns scopeOptIns) {
+	if len(rep.Skipped) > 0 {
+		fmt.Fprintf(out, "skipped %d READONLY key(s) the file changed: %v\n", len(rep.Skipped), rep.Skipped)
+	}
+	if !optIns.skip && len(rep.InSkipCategory) > 0 {
+		fmt.Fprintf(out, "skipped %d SKIP key(s) (use --include-skip to include): %v\n",
+			len(rep.InSkipCategory), rep.InSkipCategory)
+	}
+	if !optIns.hidden && len(rep.InHiddenCategory) > 0 {
+		fmt.Fprintf(out, "skipped %d hidden key(s) (use --include-hidden to include): %v\n",
+			len(rep.InHiddenCategory), rep.InHiddenCategory)
+	}
+}

pkg/catalog/walk_test.go

@@ -37,6 +37,8 @@ func TestWalk(t *testing.T) {
 		"MB_address",
 		"MB_baudrate",
 		"NomeLinea",
+		"TEST_EnableBoard",
+		"TEST_IP_Address",
 		"UL1",
 	}
 	if !equalSlices(got, want) {