MAD Designer iconMAD

Phase 6a — Connection & document (design)

Date: 2026-11-19 · Branch: windows-engine · Author: Claude Code

Intent

Give the WPF shell the connection & document layer the Mac app already has: create a new .mad from a database connection (importing its schema), edit / reconnect an existing document’s connection, and save / save-as — on top of the Phase 5 open / refresh / export slice. The connection assistant mirrors the Mac’s MADMacConnectionWindowController: a driver selector (SQLite / MySQL / Microsoft SQL Server / PostgreSQL) with driver-specific fields, a Test Connection action that reports the schema-table count, and a Create Document… / Save & Refresh action.

Goals / non-goals

Goals

  1. Create a .mad from a SQLite database (import schema); the result opens, describes columns/tables, and refreshes against the same database.
  2. A connection assistant that shows/hides fields by driver exactly as the Mac does.
  3. Test Connection connects and reports the schema-table count (or a clean error).
  4. Save and Save As write the document, reusing the engine’s write.
  5. Credentials live in Windows Credential Manager and reach the engine as the protocol’s existing credentials (user:password).
  6. Recent files is a client-side list.
  7. No crashes, no UI stalls, clean process lifecycle (Phase 5 shutdown preserved).

Non-goals (deferred, unchanged): PDF, barcodes, localization (6e), the Query / Designer / Viewer feature work (6b–6d), the one-shot CLI verbs, Apple/Linux builds.

Anti-goals: a second engine implementation, a second schema/rows wire format, silently reworking the Objective-C engine, an iOS-style file explorer, or a launch-to-Open-File-Dialog flow.

Constraints

Approaches — the one decision this sub-phase forces

The serve protocol (§6d) has open, describe, query, refresh, export, write, shutdown. It has no create and no test-connection, even though the engine already has MADHeadlessDocument createDocumentAtURL:… and MADDatabase (connect → getTables → close). This is the genuine gap the prompt flags. Three ways to close it:

Choice: A. It is minimal and protocol-shaped, reuses the engine’s own createDocumentAtURL: / MADDatabase / applyDatabaseConnection:, and is what the prompt anticipates (“keep any engine change minimal and protocol-shaped”).

Protocol addition (final shape)

Driver token is an explicit wire string: sqlite3 | mysql | sqlserver | postgres. Connection params are driver-specific and mirror the Mac form:

method params result
create path, driver, connection fields, credentials handle, filename, driver (the created document, registered like open)
test-connection driver, connection fields, credentials tableCount
connection handle driver, file/host/port/database/server
apply-connection handle, driver, connection fields, credentials {} (updates the live document’s connection)
write (changed) handle, out, optional reproducible path, bytes — now serializes the live document, not a re-open of sourceURL

credentials is the existing "user:password" split (MADCLIServeCredential). Errors use the existing exit codes: usage 1, database unreachable 3. The one-shot mad write --reproducible verb and its byte digest are untouched; serve write has no digest pin (the Phase 4 Write_ProducesACopy test only asserts a valid copy).

The WPF architecture (my calls, correctable)

Building on Phase 5’s EngineService / DocumentViewModel / hand-rolled MVVM:

Validation

Headless, through the engine, following the existing Mad.Designer.Windows.Tests pattern (the London fixture and chinook.sqlite3 at MADDesigner/Resources/Assets/Samples.xcassets/Data/chinook.dataset/):

What’s left to the builder (plan level)

Exact MADCLIServe.m helper decomposition (build-connection helper shared by create/test-connection/apply-connection; the concrete MADHeadlessDocument live-write path with an Apple fallback), the precise P/Invoke surface for Credential Manager, the XAML layout of the assistant, and the test fixtures.