feat: Implement scenario-based stateful command responses (#79)

* feat: Implement scenario-based stateful command responses

Add scenario support to transcript_map.yaml — a scenario defines an
ordered sequence of (command, transcript) pairs layered on top of a
platform. Each SSH session gets its own sequence pointer that advances
as commands match the next expected step; non-matching commands fall
through to normal command_transcripts behavior.

Schema:
  scenarios:
    csr1000v-add-interface:
      platform: csr1000v
      sequence:
        - command: show running-config
          transcript: transcripts/scenarios/.../before.txt
        - command: interface GigabitEthernet0/0/2
          transcript: transcripts/generic_empty_return.txt
        - command: show running-config
          transcript: transcripts/scenarios/.../after.txt

Inventory entries can now reference either platform or scenario
(mutually exclusive). Validation checks scenario paths and platform
references at startup. Sequence pointer resets on every new SSH
connection.

Closes #27

* fix: Extract resolveListeners helper to reduce run() cyclomatic complexity

Extracts inventory/platform resolution into resolveListeners() to bring
run() complexity below the gocyclo threshold of 15. Renames listenerSpec
to listenerConfig for clarity. Also fixes gofmt formatting in
ciscohandlers_test.go.

Author: lykinsbd

cissh.go

@@ -22,9 +22,54 @@ import (
 	"github.com/tbotnz/cisshgo/utils"
 )
 
-type listenerSpec struct {
-	fd   *fakedevices.FakeDevice
-	port int
+type listenerConfig struct {
+	fd       *fakedevices.FakeDevice
+	port     int
+	sequence []utils.SequenceStep // nil for platform-only listeners
+}
+
+func resolveListeners(cli utils.CLI, tm utils.TranscriptMap, baseDir string) ([]listenerConfig, error) {
+	if cli.Inventory == "" {
+		fd, err := fakedevices.InitGeneric(cli.Platform, tm, baseDir)
+		if err != nil {
+			return nil, err
+		}
+		var configs []listenerConfig
+		for port := cli.StartingPort; port < cli.StartingPort+cli.Listeners; port++ {
+			configs = append(configs, listenerConfig{fd, port, nil})
+		}
+		return configs, nil
+	}
+
+	inv, err := utils.LoadInventory(cli.Inventory)
+	if err != nil {
+		return nil, err
+	}
+
+	var configs []listenerConfig
+	port := cli.StartingPort
+	for _, entry := range inv.Devices {
+		if entry.Scenario != "" {
+			fd, seq, err := fakedevices.InitScenario(entry.Scenario, tm, baseDir)
+			if err != nil {
+				return nil, err
+			}
+			for i := 0; i < entry.Count; i++ {
+				configs = append(configs, listenerConfig{fd, port, seq})
+				port++
+			}
+		} else {
+			fd, err := fakedevices.InitGeneric(entry.Platform, tm, baseDir)
+			if err != nil {
+				return nil, err
+			}
+			for i := 0; i < entry.Count; i++ {
+				configs = append(configs, listenerConfig{fd, port, nil})
+				port++
+			}
+		}
+	}
+	return configs, nil
 }
 
 func run(ctx context.Context, cli utils.CLI) error {
@@ -38,47 +83,30 @@ func run(ctx context.Context, cli utils.CLI) error {
 		return err
 	}
 
-	var specs []listenerSpec
+	configs, err := resolveListeners(cli, myTranscriptMap, baseDir)
+	if err != nil {
+		return err
+	}
 
-	if cli.Inventory != "" {
-		inv, err := utils.LoadInventory(cli.Inventory)
-		if err != nil {
-			return err
-		}
-		port := cli.StartingPort
-		for _, entry := range inv.Devices {
-			fd, err := fakedevices.InitGeneric(entry.Platform, myTranscriptMap, baseDir)
-			if err != nil {
-				return err
+	var wg sync.WaitGroup
+	for _, config := range configs { // coverage-ignore
+		wg.Add(1)
+		go func(cfg listenerConfig) {
+			defer wg.Done()
+			var err error
+			if cfg.sequence != nil {
+				err = sshlisteners.ScenarioListener(ctx, cfg.fd, cfg.sequence, cfg.port)
+			} else {
+				err = sshlisteners.GenericListener(ctx, cfg.fd, cfg.port, handlers.GenericCiscoHandler)
 			}
-			for i := 0; i < entry.Count; i++ {
-				specs = append(specs, listenerSpec{fd, port})
-				port++
+			if err != nil {
+				log.Printf("listener on port %d: %v", cfg.port, err)
 			}
-		}
-	} else {
-		fd, err := fakedevices.InitGeneric(cli.Platform, myTranscriptMap, baseDir)
-		if err != nil {
-			return err
-		}
-		for port := cli.StartingPort; port < cli.StartingPort+cli.Listeners; port++ {
-			specs = append(specs, listenerSpec{fd, port})
-		}
+		}(config)
 	}
 
-	var wg sync.WaitGroup
-	for _, spec := range specs { // coverage-ignore
-		wg.Add(1)                                       // coverage-ignore
-		go func(fd *fakedevices.FakeDevice, port int) { // coverage-ignore
-			defer wg.Done()                                                                                   // coverage-ignore
-			if err := sshlisteners.GenericListener(ctx, fd, port, handlers.GenericCiscoHandler); err != nil { // coverage-ignore
-				log.Printf("listener on port %d: %v", port, err) // coverage-ignore
-			} // coverage-ignore
-		}(spec.fd, spec.port) // coverage-ignore
-	} // coverage-ignore
-
-	wg.Wait()  // coverage-ignore
-	return nil // coverage-ignore
+	wg.Wait()
+	return nil
 }
 
 func main() { // coverage-ignore

fakedevices/genericFakeDevice.go

@@ -50,6 +50,32 @@ func readFile(filename string) (string, error) {
 	return string(content), nil
 }
 
+// InitScenario builds a FakeDevice for a named scenario, loading the base platform
+// and returning the pre-loaded sequence steps alongside the device.
+func InitScenario(scenarioName string, tm utils.TranscriptMap, baseDir string) (*FakeDevice, []utils.SequenceStep, error) {
+	s, ok := tm.Scenarios[scenarioName]
+	if !ok {
+		return nil, nil, fmt.Errorf("scenario %q not found in transcript map", scenarioName)
+	}
+	fd, err := InitGeneric(s.Platform, tm, baseDir)
+	if err != nil {
+		return nil, nil, err
+	}
+	steps := make([]utils.SequenceStep, len(s.Sequence))
+	for i, step := range s.Sequence {
+		path := step.Transcript
+		if !filepath.IsAbs(path) {
+			path = filepath.Join(baseDir, path)
+		}
+		content, err := readFile(path)
+		if err != nil {
+			return nil, nil, err
+		}
+		steps[i] = utils.SequenceStep{Command: step.Command, Transcript: content}
+	}
+	return fd, steps, nil
+}
+
 // InitGeneric builds a FakeDevice struct for use with cisshgo.
 // baseDir is the directory from which transcript paths are resolved (typically
 // the directory containing the transcript map file).

fakedevices/genericFakeDevice_test.go

@@ -158,6 +158,14 @@ func TestTranscriptMapIntegrity(t *testing.T) {
 			}
 		}
 	}
+	for name, s := range tm.Scenarios {
+		for i, step := range s.Sequence {
+			referenced[step.Transcript] = true
+			if _, err := os.Stat(step.Transcript); err != nil {
+				t.Errorf("scenario %q step %d (%q): file not found: %s", name, i, step.Command, step.Transcript)
+			}
+		}
+	}
 
 	// Walk transcripts/ and flag unreferenced .txt files
 	err = filepath.WalkDir("transcripts", func(path string, d fs.DirEntry, err error) error {
@@ -177,3 +185,37 @@ func TestTranscriptMapIntegrity(t *testing.T) {
 		t.Fatalf("walking transcripts dir: %v", err)
 	}
 }
+
+func TestInitScenario(t *testing.T) {
+	if err := os.Chdir(".."); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { os.Chdir("fakedevices") })
+
+	tm, err := utils.LoadTranscriptMap("transcripts/transcript_map.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	fd, steps, err := InitScenario("csr1000v-add-interface", tm, ".")
+	if err != nil {
+		t.Fatalf("InitScenario: %v", err)
+	}
+	if fd.Platform != "csr1000v" {
+		t.Errorf("Platform = %q, want csr1000v", fd.Platform)
+	}
+	if len(steps) != 5 {
+		t.Errorf("steps len = %d, want 5", len(steps))
+	}
+	if steps[0].Command != "show running-config" {
+		t.Errorf("steps[0].Command = %q, want 'show running-config'", steps[0].Command)
+	}
+}
+
+func TestInitScenario_UnknownScenario(t *testing.T) {
+	tm := utils.TranscriptMap{Platforms: map[string]utils.TranscriptMapPlatform{}}
+	_, _, err := InitScenario("nonexistent", tm, ".")
+	if err == nil {
+		t.Error("expected error for unknown scenario")
+	}
+}

ssh_server/handlers/ciscohandlers.go

@@ -16,6 +16,15 @@ import (
 
 // GenericCiscoHandler function handles generic Cisco style sessions
 func GenericCiscoHandler(myFakeDevice *fakedevices.FakeDevice) ssh.Handler {
+	return genericCiscoSession(myFakeDevice, nil)
+}
+
+// GenericCiscoScenarioHandler returns an ssh.Handler that plays back a scenario sequence.
+func GenericCiscoScenarioHandler(myFakeDevice *fakedevices.FakeDevice, sequence []utils.SequenceStep) ssh.Handler {
+	return genericCiscoSession(myFakeDevice, sequence)
+}
+
+func genericCiscoSession(myFakeDevice *fakedevices.FakeDevice, sequence []utils.SequenceStep) ssh.Handler {
 	return func(s ssh.Session) {
 
 		// Exec mode: client sent a command directly (e.g., ssh host "show version")
@@ -34,7 +43,8 @@ func GenericCiscoHandler(myFakeDevice *fakedevices.FakeDevice) ssh.Handler {
 			return
 		}
 
-		// Interactive shell mode
+		// Interactive shell mode — sequence pointer resets per session
+		seqIdx := 0
 		contextState := myFakeDevice.ContextSearch["base"]
 		t := term.NewTerminal(s, myFakeDevice.Hostname+contextState)
 
@@ -45,7 +55,7 @@ func GenericCiscoHandler(myFakeDevice *fakedevices.FakeDevice) ssh.Handler {
 			}
 			log.Println(userInput)
 
-			done := handleShellInput(t, userInput, myFakeDevice, &contextState)
+			done := handleShellInput(t, userInput, myFakeDevice, &contextState, sequence, &seqIdx)
 			if done {
 				break
 			}
@@ -56,7 +66,7 @@ func GenericCiscoHandler(myFakeDevice *fakedevices.FakeDevice) ssh.Handler {
 
 // handleShellInput processes a single line of user input in interactive shell mode.
 // Returns true if the session should be terminated.
-func handleShellInput(t *term.Terminal, userInput string, fd *fakedevices.FakeDevice, contextState *string) bool {
+func handleShellInput(t *term.Terminal, userInput string, fd *fakedevices.FakeDevice, contextState *string, sequence []utils.SequenceStep, seqIdx *int) bool {
 	if userInput == "" {
 		t.Write([]byte(""))
 		return false
@@ -102,12 +112,28 @@ func handleShellInput(t *term.Terminal, userInput string, fd *fakedevices.FakeDe
 	}
 
 	// Match against supported commands
-	return dispatchCommand(t, userInput, fd)
+	return dispatchCommand(t, userInput, fd, sequence, seqIdx)
 }
 
-// dispatchCommand matches userInput against supported commands and writes the response.
+// dispatchCommand matches userInput against the active sequence step first, then supported commands.
 // Returns true if the session should be terminated.
-func dispatchCommand(t *term.Terminal, userInput string, fd *fakedevices.FakeDevice) bool {
+func dispatchCommand(t *term.Terminal, userInput string, fd *fakedevices.FakeDevice, sequence []utils.SequenceStep, seqIdx *int) bool {
+	// Check if the next sequence step matches
+	if seqIdx != nil && *seqIdx < len(sequence) {
+		step := sequence[*seqIdx]
+		match, _, multipleMatches, _ := utils.CmdMatch(userInput, map[string]string{step.Command: ""})
+		if match && !multipleMatches {
+			output, err := fakedevices.TranscriptReader(step.Transcript, fd)
+			if err != nil {
+				log.Println(err)
+				return true
+			}
+			t.Write(append([]byte(output), '\n'))
+			*seqIdx++
+			return false
+		}
+	}
+
 	match, matchedCommand, multipleMatches, err := utils.CmdMatch(userInput, fd.SupportedCommands)
 	if err != nil {
 		log.Println(err) // coverage-ignore // CmdMatch never returns errors

ssh_server/handlers/ciscohandlers_test.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/gliderlabs/ssh"
 	"github.com/tbotnz/cisshgo/fakedevices"
+	"github.com/tbotnz/cisshgo/utils"
 )
 
 // newTestDevice creates a FakeDevice for testing without reading files from disk.
@@ -362,3 +363,51 @@ func TestHandler_TranscriptReaderError(t *testing.T) {
 	// Should not crash, just close the session
 	_ = interact(t, addr, []string{"show bad"})
 }
+
+func TestHandler_ScenarioSequence(t *testing.T) {
+	fd := newTestDevice()
+	sequence := []utils.SequenceStep{
+		{Command: "show running-config", Transcript: "config before\n"},
+		{Command: "interface GigabitEthernet0/0/2", Transcript: ""},
+		{Command: "show running-config", Transcript: "config after\n"},
+	}
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	addr := ln.Addr().String()
+	ln.Close()
+
+	srv := &ssh.Server{
+		Addr:    addr,
+		Handler: GenericCiscoScenarioHandler(fd, sequence),
+		PasswordHandler: func(ctx ssh.Context, pass string) bool {
+			return pass == fd.Password
+		},
+	}
+	go func() { _ = srv.ListenAndServe() }()
+
+	for i := 0; i < 20; i++ {
+		conn, dialErr := net.DialTimeout("tcp", addr, 100*time.Millisecond)
+		if dialErr == nil {
+			conn.Close()
+			break
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	defer srv.Close()
+
+	// All three steps in a single session — pointer advances across commands
+	out := interact(t, addr, []string{
+		"show running-config",            // step 0 → "config before"
+		"interface GigabitEthernet0/0/2", // step 1 → ""
+		"show running-config",            // step 2 → "config after"
+	})
+	if !strings.Contains(out, "config before") {
+		t.Errorf("expected 'config before' in output, got:\n%s", out)
+	}
+	if !strings.Contains(out, "config after") {
+		t.Errorf("expected 'config after' in output, got:\n%s", out)
+	}
+}

ssh_server/handlers/handlers.go

@@ -4,7 +4,11 @@ import (
 	"github.com/gliderlabs/ssh"
 
 	"github.com/tbotnz/cisshgo/fakedevices"
+	"github.com/tbotnz/cisshgo/utils"
 )
 
 // PlatformHandler defines a default type for all platform handlers
 type PlatformHandler func(*fakedevices.FakeDevice) ssh.Handler
+
+// ScenarioHandler defines a handler type that includes a sequence of steps
+type ScenarioHandler func(*fakedevices.FakeDevice, []utils.SequenceStep) ssh.Handler

ssh_server/sshlisteners/sshlisteners.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/tbotnz/cisshgo/fakedevices"
 	"github.com/tbotnz/cisshgo/ssh_server/handlers"
+	"github.com/tbotnz/cisshgo/utils"
 )
 
 // GenericListener starts an SSH server on the given port and blocks until ctx is cancelled.
@@ -20,12 +21,26 @@ func GenericListener(
 	portNumber int,
 	myHandler handlers.PlatformHandler,
 ) error {
+	return listen(ctx, myFakeDevice, portNumber, myHandler(myFakeDevice.Copy()))
+}
+
+// ScenarioListener starts an SSH server that plays back a scenario sequence.
+func ScenarioListener(
+	ctx context.Context,
+	myFakeDevice *fakedevices.FakeDevice,
+	sequence []utils.SequenceStep,
+	portNumber int,
+) error {
+	return listen(ctx, myFakeDevice, portNumber, handlers.GenericCiscoScenarioHandler(myFakeDevice.Copy(), sequence))
+}
+
+func listen(ctx context.Context, myFakeDevice *fakedevices.FakeDevice, portNumber int, handler ssh.Handler) error {
 	portString := ":" + strconv.Itoa(portNumber)
 	log.Printf("Starting cissh.go ssh server on port %s\n", portString)
 
 	srv := &ssh.Server{
 		Addr:    portString,
-		Handler: myHandler(myFakeDevice.Copy()),
+		Handler: handler,
 		PasswordHandler: func(sshCtx ssh.Context, pass string) bool {
 			return pass == myFakeDevice.Password
 		},