ipswap/claude.md

ipswap — Windows IP preset switcher

Purpose

A tray-resident Windows utility for rapidly switching a network adapter between saved static-IP configurations. Built for field/support work where a laptop needs to hop between customer subnets (broadcast control networks, media networks, management VLANs) many times a day.

Working name ipswap — rename freely.

Stack

• Go, single static .exe, no runtime dependency, no CGO.
• Tray: fyne.io/systray (pure-Go on Windows — keeps GOOS=windows go build cross-compiling from Linux CI without Wine).
• Fast-path dialogs: native Win32 MessageBoxW via syscall.NewLazyDLL("user32.dll"). No GUI toolkit.
• Editor UI: embedded static web app (embed.FS) served on 127.0.0.1:<random port>, opened in the default browser.
• No CGO anywhere. If a dependency needs it, pick another dependency.

Architecture

Two interaction paths, deliberately split:

Fast path (native, no browser) Tray icon → menu of presets, grouped into submenus → click → confirmation MessageBox showing a before/after diff → Yes → apply → tray tooltip updates to the active preset name.

Slow path (browser) Tray → "Manage presets…" → spawns local HTTP server, opens default browser to http://127.0.0.1:<port>/?t=<session-token>. Full CRUD on presets, adapter picker, import/export, settings. Server shuts down when the browser session goes idle (no heartbeat for 5 min) or on app exit.

Rationale: switching must be two clicks and zero browser. Editing 50 presets in a MessageBox would be miserable.

Web UI styling

Use the apointless.css design system: dark-first, JetBrains Mono + DM Sans, blue accent #3b82f6, bg #0b0d11, surfaces #12151b/#1a1e28/#232838, subtle blue grid via body::before, semantic colour tokens, light mode via html.light class + localStorage. Use its existing components (cards, stat cards, badges, pills, buttons, inputs, tables, alerts, code blocks, spinners) rather than inventing new ones.

Data model

Stored at %APPDATA%\ipswap\presets.json. Settings at %APPDATA%\ipswap\config.json. Log at %APPDATA%\ipswap\ipswap.log (rotating, keep last 5 × 1 MB).

{
  "version": 1,
  "presets": [
    {
      "id": "01J8X...",
      "name": "Artist frame — control",
      "group": "Riedel",
      "adapter": "Ethernet",
      "mode": "static",
      "primary": {
        "address": "192.168.42.100",
        "prefix": 24,
        "gateway": "192.168.42.1",
        "gateway_metric": 0
      },
      "secondary": [
        { "address": "10.0.10.50", "prefix": 24 }
      ],
      "dns": {
        "mode": "static",
        "servers": ["192.168.42.1", "1.1.1.1"]
      },
      "notes": "Frame A, rack 3"
    },
    {
      "id": "01J8Y...",
      "name": "DHCP",
      "group": "General",
      "adapter": "Ethernet",
      "mode": "dhcp",
      "dns": { "mode": "dhcp" }
    }
  ]
}

Notes:

• adapter is the Windows friendly name (Ethernet, Wi-Fi, Ethernet 3). Bound per preset and editable in the preset editor. net.Interfaces() on Windows returns these names and they match what netsh expects.
• Subnet mask stored internally as an integer prefix. The editor must accept both /24 and 255.255.255.0 on input and display whichever the user last used (per-preset display preference is overkill — a single global setting is fine).
• gateway optional. gateway_metric 0 = automatic.
• Wi-Fi adapters are supported and treated identically. No special-casing.

Applying a preset

Applies are destructive: after apply, the adapter has exactly the addresses in the preset and nothing else.

netsh interface ipv4 set address … static replaces the primary but leaves previously added secondary addresses in place, so a naive implementation leaks addresses across switches. Sequence:

1. Enumerate current IPv4 addresses on the target adapter.
2. netsh interface ipv4 delete address name="<adapter>" addr=<each existing> for every existing static address.
3. Set the primary: netsh interface ipv4 set address name="<adapter>" static <addr> <mask> <gateway> <gwmetric>
4. Add each secondary: netsh interface ipv4 add address name="<adapter>" <addr> <mask>
5. DNS static: netsh interface ipv4 set dnsservers name="<adapter>" static <first> primary validate=no then for each subsequent, netsh interface ipv4 add dnsservers name="<adapter>" <addr> index=<n>
6. DNS DHCP: netsh interface ipv4 set dnsservers name="<adapter>" source=dhcp

For mode: "dhcp": netsh interface ipv4 set address name="<adapter>" source=dhcp (this also clears statics, so step 2 can be skipped).

Fallback if step 2 proves unreliable: set the adapter to DHCP first to flush statics, then immediately apply the static config. Costs ~1s and a brief DHCP solicit — use only if needed.

Run every netsh invocation off the UI goroutine. Applies take 1–3 s. Capture stdout/stderr and exit code, log all of it, surface failures in a MessageBox with the raw netsh output included.

Confirmation prompt

Before applying, show a Win32 MessageBox (MB_YESNO | MB_ICONQUESTION) containing:

Apply preset "Artist frame — control" to adapter "Ethernet"?

CURRENT
  192.168.1.87/24 (DHCP)
  Gateway: 192.168.1.1
  DNS: 192.168.1.1

NEW
  192.168.42.100/24
  + 10.0.10.50/24
  Gateway: 192.168.42.1
  DNS: 192.168.42.1, 1.1.1.1

Read the current config live at prompt time, not from cache. A "don't ask again for this session" checkbox is out of scope — the prompt is the safety net.

Active preset detection

On startup, after any apply, and every 30 s, read each adapter's live config and mark any preset that matches exactly. Show a check/radio mark next to it in the tray menu and set the tray tooltip to ipswap — <preset name> (or ipswap — unmatched).

Elevation

Manifest as asInvoker, not requireAdministrator. On a machine with UAC relaxed or an already-elevated parent, this means zero prompts.

At startup, check whether the process token is actually elevated (windows.Token.IsElevated() or GetTokenInformation/TokenElevation). If it is not:

• Do not fail, do not block startup.
• Add a tray menu item "Relaunch as administrator" that re-execs via ShellExecuteW with the runas verb.
• If an apply fails with an elevation error, the failure MessageBox offers the same relaunch action.

Being in the Administrators group is not the same as holding an elevated token — with UAC on, the process gets a filtered token and netsh set address returns "The requested operation requires elevation." This design costs nothing on a permissive machine and degrades cleanly on a locked-down one.

Tray menu layout

ipswap — Artist frame — control
─────────────────────────────
Riedel                    ▸   [submenu of presets in this group]
Herespace                 ▸
General                   ▸
─────────────────────────────
Manage presets…
Check for updates
─────────────────────────────
Relaunch as administrator     [only shown if not elevated]
Exit

Presets with no group go into a top-level "Ungrouped" submenu. Design for ~50 presets: submenus are mandatory, a flat list is not acceptable. No global hotkeys.

Import / export

• Export: write the full presets.json, or a filtered subset by group, to a user-chosen path. Include version.
• Import: merge or replace, user's choice. On merge, collide on id → keep both, suffix the incoming name with (imported). Validate the schema and reject with a clear error rather than partially importing.

This is the mechanism for shipping preset packs to colleagues, so keep the file format clean and hand-editable.

Update checker

Gitea-hosted, same pattern as ShippingTracker.

• On startup (and on demand from the tray), GET https://<gitea-host>/api/v1/repos/<owner>/<repo>/releases/latest.
• Compare the release tag against the compiled-in version using semver.
• If newer: tray menu gains "Update available — v1.2.0" as the top item.
• On click: download the .exe asset to %TEMP%, verify the SHA256 against a checksum published in the release body or as a sibling asset, then write a small batch/helper that waits for the parent to exit, swaps the binary, and relaunches.
• Never auto-install. Never block startup on the network call — run it in a goroutine with a short timeout and fail silently to the log.

Build & CI

• GOOS=windows GOARCH=amd64 go build -ldflags="-H windowsgui -X main.version=$VERSION". -H windowsgui suppresses the console window.
• Embed an icon and a manifest (asInvoker, dpiAware) — goversioninfo or a .syso.
• Gitea Actions: build on tag, attach the .exe and a SHA256SUMS file to the release. Pure Go means no Wine step is needed.

Out of scope for v1

• Revert / restore-previous / timed auto-revert.
• Post-apply connectivity verification (ping/ARP). The confirmation diff is the check.
• Global hotkeys.
• IPv6.
• Adapter matching by MAC address (name only for now — worth revisiting if dock/USB-NIC name drift becomes a problem).
• Per-preset scripts or hooks.

Open questions for Ben

1. Gitea host/owner/repo for the update endpoint.
2. Whether the app should start with Windows (registry Run key, toggleable in settings) — assumed yes, off by default.
3. Confirm the split UI (native tray + browser editor) is right. You picked "menu only" for hotkeys but also wanted a confirmation prompt and 50 presets — those pull toward needing a real editor window, hence the browser. Say if you'd rather have a native window instead.

Side note

Claude will be running in a tmux session