Adom Desktop - KiCad Bridge

"""Tour step definitions — every step shows something visual in KiCad."""

import os

# Action types — each one triggers a visible change on screen
DISPLAY = "display"           # Show text in panel only (intro/outro)
BRIDGE = "bridge"             # Bridge command + show data
BRIDGE_VISUAL = "bridge_vis"  # Bridge command that opens/changes KiCad visually
IPC_TEST = "ipc_test"         # Run IPC test, show section
IPC_LAYER = "ipc_layer"       # Switch active layer (visible in pcbnew)
WIN_CLOSE = "win_close"       # Close a window by title substring

# Demo project paths (resolved at import time)
_TOUR_DIR = os.path.dirname(os.path.abspath(__file__))
_DEMO_DIR = os.path.join(_TOUR_DIR, "demo-project")
SCH_PATH = os.path.join(_DEMO_DIR, "demo-project.kicad_sch").replace("/", "\\")
PCB_PATH = os.path.join(_DEMO_DIR, "demo-project.kicad_pcb").replace("/", "\\")

TOUR_STEPS = [
    # ══════════════════════════════════════════════════════════════
    # Act 1: "Meet Your Design — Schematic"
    # ══════════════════════════════════════════════════════════════
    {
        "act": "Act 1 — Schematic",
        "title": "Welcome to the Gallia Tour",
        "description": (
            "Gallia gives AI agents full control over KiCad. "
            "Every step in this tour triggers a real action in "
            "KiCad — watch the editor windows on the left.\n\n"
            "Let's start by opening your schematic."
        ),
        "action": BRIDGE_VISUAL,
        "command": "open_schematic",
        "args": {"filePath": SCH_PATH},
        "wait_window": "Schematic Editor",
        "delay_before": 1.0,
        "delay_after": 4.0,
    },
    {
        "act": "Act 1 — Schematic",
        "title": "Schematic Statistics",
        "description": (
            "Parsing the schematic file to extract statistics — "
            "component counts, wires, labels, and hierarchy. "
            "The schematic is open on the left so you can "
            "visually verify the numbers."
        ),
        "action": BRIDGE,
        "command": "get_schematic_stats",
        "args": {"filePath": SCH_PATH},
        "delay_before": 1.0,
        "delay_after": 5.0,
    },
    {
        "act": "Act 1 — Schematic",
        "title": "Schematic Hierarchy",
        "description": (
            "Mapping the hierarchical sheet tree. Complex designs "
            "use sub-sheets to organize blocks. Look at the "
            "schematic — each sheet instance maps to a node here."
        ),
        "action": BRIDGE,
        "command": "get_schematic_hierarchy",
        "args": {"filePath": SCH_PATH},
        "delay_before": 1.0,
        "delay_after": 5.0,
    },
    {
        "act": "Act 1 — Schematic",
        "title": "List Components",
        "description": (
            "Extracting every component from the schematic. "
            "Each entry shows the reference designator, value, "
            "and library symbol — matching what you see placed "
            "on the schematic sheet."
        ),
        "action": BRIDGE,
        "command": "list_schematic_components",
        "args": {"filePath": SCH_PATH},
        "delay_before": 1.0,
        "delay_after": 5.0,
    },

    # ══════════════════════════════════════════════════════════════
    # Act 2: "PCB Layout"
    # ══════════════════════════════════════════════════════════════
    {
        "act": "Act 2 — PCB Layout",
        "title": "Open PCB Editor",
        "description": (
            "Closing the schematic and opening the PCB layout. "
            "This is where copper traces, footprints, and the "
            "physical board design live."
        ),
        "action": BRIDGE_VISUAL,
        "command": "open_board",
        "args": {"filePath": PCB_PATH},
        "close_first": "Schematic Editor",
        "wait_window": "PCB Editor",
        "delay_before": 1.0,
        "delay_after": 4.0,
    },
    {
        "act": "Act 2 — PCB Layout",
        "title": "PCB Statistics",
        "description": (
            "Board dimensions, layer count, track count, vias, "
            "and footprints. Look at the board on the left — "
            "these numbers describe exactly what you see."
        ),
        "action": BRIDGE,
        "command": "get_pcb_statistics",
        "args": {"filePath": PCB_PATH},
        "delay_before": 1.0,
        "delay_after": 5.0,
    },
    {
        "act": "Act 2 — PCB Layout",
        "title": "Net List",
        "description": (
            "Every electrical connection on the board is a net. "
            "Each colored ratsnest line in pcbnew represents one "
            "of these nets connecting pads together."
        ),
        "action": BRIDGE,
        "command": "list_pcb_nets",
        "args": {"filePath": PCB_PATH},
        "delay_before": 1.0,
        "delay_after": 5.0,
    },
    {
        "act": "Act 2 — PCB Layout",
        "title": "Bill of Materials",
        "description": (
            "The BOM lists every component needed to build this "
            "board. Each footprint you see placed on the PCB "
            "corresponds to a row in this table."
        ),
        "action": BRIDGE,
        "command": "generate_bom",
        "args": {"filePath": SCH_PATH},
        "delay_before": 1.0,
        "delay_after": 5.0,
    },

    # ══════════════════════════════════════════════════════════════
    # Act 3: "Live IPC Control"
    # ══════════════════════════════════════════════════════════════
    {
        "act": "Act 3 — Live IPC",
        "title": "IPC: Ping & Version",
        "description": (
            "Now talking directly to KiCad's running process via "
            "IPC (protobuf over NNG). This is a live connection — "
            "not file parsing. Ping confirms KiCad is listening."
        ),
        "action": IPC_TEST,
        "section": 1,
        "delay_before": 1.0,
        "delay_after": 4.0,
    },
    {
        "act": "Act 3 — Live IPC",
        "title": "IPC: Board Layers",
        "description": (
            "Querying enabled layers directly from KiCad's memory. "
            "These match the layer list in pcbnew's right panel. "
            "Next we'll switch between them live."
        ),
        "action": IPC_TEST,
        "section": 4,
        "delay_before": 1.0,
        "delay_after": 4.0,
    },
    {
        "act": "Act 3 — Live IPC",
        "title": "Switch to B.Cu (Back Copper)",
        "description": (
            "Watch KiCad! Sending an IPC command to switch the "
            "active layer to B.Cu. The layer selector in pcbnew "
            "will change and the board rendering will update."
        ),
        "action": IPC_LAYER,
        "layer_id": 34,
        "layer_name": "B.Cu",
        "delay_before": 1.5,
        "delay_after": 3.0,
    },
    {
        "act": "Act 3 — Live IPC",
        "title": "Switch to In1.Cu (Inner Layer)",
        "description": (
            "Switching to inner copper layer 1. The PCB editor "
            "highlights the active layer — watch the color "
            "change in the layer panel on the right."
        ),
        "action": IPC_LAYER,
        "layer_id": 4,
        "layer_name": "In1.Cu",
        "delay_before": 1.5,
        "delay_after": 3.0,
    },
    {
        "act": "Act 3 — Live IPC",
        "title": "Restore F.Cu (Front Copper)",
        "description": (
            "Back to front copper. An AI agent can switch layers "
            "to inspect routing, check clearances, or prepare "
            "specific layers for export."
        ),
        "action": IPC_LAYER,
        "layer_id": 3,
        "layer_name": "F.Cu",
        "delay_before": 1.5,
        "delay_after": 3.0,
    },

    # ══════════════════════════════════════════════════════════════
    # Act 4: "Symbol Library"
    # ══════════════════════════════════════════════════════════════
    {
        "act": "Act 4 — Libraries",
        "title": "Search Symbol Libraries",
        "description": (
            "Searching KiCad's symbol libraries for 'opamp'. "
            "KiCad ships with hundreds of libraries — this "
            "command searches across all of them instantly."
        ),
        "action": BRIDGE,
        "command": "search_symbols",
        "args": {"query": "opamp"},
        "delay_before": 1.0,
        "delay_after": 4.0,
    },
    {
        "act": "Act 4 — Libraries",
        "title": "Open Symbol Editor: LM358",
        "description": (
            "Opening the Symbol Editor and loading the LM358 "
            "dual op-amp. Watch KiCad — the symbol will appear "
            "with all its pins, ready for inspection."
        ),
        "action": BRIDGE_VISUAL,
        "command": "open_symbol_editor",
        "args": {"symbolName": "LM358", "libraryName": "Amplifier_Operational"},
        "close_first": "PCB Editor",
        "wait_window": "Symbol Editor",
        "delay_before": 1.0,
        "delay_after": 5.0,
    },
    {
        "act": "Act 4 — Libraries",
        "title": "Symbol Pin Details",
        "description": (
            "Extracting pin information for the LM358. Each pin "
            "you see in the Symbol Editor on the left matches "
            "a row here — name, number, electrical type."
        ),
        "action": BRIDGE,
        "command": "get_symbol_info",
        "args": {"symbol_name": "Amplifier_Operational:LM358"},
        "delay_before": 1.0,
        "delay_after": 5.0,
    },

    # ══════════════════════════════════════════════════════════════
    # Act 5: "Design Checks"
    # ══════════════════════════════════════════════════════════════
    {
        "act": "Act 5 — Design Checks",
        "title": "Design Rule Check (DRC)",
        "description": (
            "Running DRC against the PCB. This checks for "
            "manufacturing violations — clearance errors, "
            "unconnected nets, invalid track widths. "
            "Opening the board so you can see the layout."
        ),
        "action": BRIDGE_VISUAL,
        "command": "open_board",
        "args": {"filePath": PCB_PATH},
        "close_first": "Symbol Editor",
        "wait_window": "PCB Editor",
        "post_command": "run_drc",
        "post_args": {"filePath": PCB_PATH},
        "delay_before": 1.0,
        "delay_after": 5.0,
    },
    {
        "act": "Act 5 — Design Checks",
        "title": "Electrical Rules Check (ERC)",
        "description": (
            "Running ERC against the schematic. This validates "
            "pin connections, power flags, and net consistency. "
            "Opening the schematic to show what's being checked."
        ),
        "action": BRIDGE_VISUAL,
        "command": "open_schematic",
        "args": {"filePath": SCH_PATH},
        "close_first": "PCB Editor",
        "wait_window": "Schematic Editor",
        "post_command": "run_erc",
        "post_args": {"filePath": SCH_PATH},
        "delay_before": 1.0,
        "delay_after": 5.0,
    },

    # ══════════════════════════════════════════════════════════════
    # Finale
    # ══════════════════════════════════════════════════════════════
    {
        "act": "Finale",
        "title": "Tour Complete!",
        "description": (
            "You've just seen Gallia control KiCad through:\n\n"
            "• 37 Python bridge commands (schematic, PCB, BOM, "
            "library search, DRC/ERC)\n\n"
            "• 15 Rust IPC commands (ping, version, layers, "
            "stackup, live layer switching)\n\n"
            "All available to AI agents for automated PCB "
            "engineering workflows."
        ),
        "action": DISPLAY,
        "delay_before": 1.0,
        "delay_after": 10.0,
    },
]