feat(desktop): mildstack-cli integration

Author: michasdev

.gitignore

@@ -16,3 +16,6 @@ AGENTS.md
 
 # go binary
 mildstack
+
+*.env*
+!.env.example

apps/desktop/.env.example

@@ -0,0 +1,3 @@
+
+# The path or command to the mildstack binary
+MAIN_VITE_MILDSTACK_EXECUTABLE=

apps/desktop/src/main/dynamodb-ipc.ts

@@ -1,5 +1,5 @@
-import { ipcMain } from 'electron'
 import { getActiveInstancePort } from './instance-state'
+import { registerValidatedHandler } from './ipc-middleware'
 import {
   DynamoDBClient,
   ListTablesCommand,
@@ -79,12 +79,12 @@ type DynamoDBClientCacheEntry = {
 const clientCache = new Map<string, DynamoDBClientCacheEntry>()
 
 export function registerDynamoDBIpcHandlers(): void {
-  ipcMain.handle('dynamodb:listTables', async (_event, args: { region?: string }) => {
+  registerValidatedHandler('dynamodb:listTables', async (_event, args: { region?: string }) => {
     const response = await getClient(args.region).send(new ListTablesCommand({}))
     return response.TableNames ?? []
   })
 
-  ipcMain.handle('dynamodb:describeTable', async (_event, args: DescribeTableArgs) => {
+  registerValidatedHandler('dynamodb:describeTable', async (_event, args: DescribeTableArgs) => {
     const response = await getClient(args.region).send(
       new DescribeTableCommand({ TableName: args.tableName })
     )
@@ -136,7 +136,7 @@ export function registerDynamoDBIpcHandlers(): void {
     }
   })
 
-  ipcMain.handle('dynamodb:createTable', async (_event, args: CreateTableArgs) => {
+  registerValidatedHandler('dynamodb:createTable', async (_event, args: CreateTableArgs) => {
     await getClient(args.region).send(
       new CreateTableCommand({
         TableName: args.tableName,
@@ -148,14 +148,14 @@ export function registerDynamoDBIpcHandlers(): void {
     return null
   })
 
-  ipcMain.handle('dynamodb:deleteTable', async (_event, args: { tableName: string; region?: string }) => {
+  registerValidatedHandler('dynamodb:deleteTable', async (_event, args: { tableName: string; region?: string }) => {
     await getClient(args.region).send(
       new DeleteTableCommand({ TableName: args.tableName })
     )
     return null
   })
 
-  ipcMain.handle('dynamodb:scan', async (_event, args: ScanArgs) => {
+  registerValidatedHandler('dynamodb:scan', async (_event, args: ScanArgs) => {
     const params: ScanCommandInput = {
       TableName: args.tableName,
       ExclusiveStartKey: args.exclusiveStartKey,
@@ -180,7 +180,7 @@ export function registerDynamoDBIpcHandlers(): void {
     }
   })
 
-  ipcMain.handle('dynamodb:query', async (_event, args: QueryArgs) => {
+  registerValidatedHandler('dynamodb:query', async (_event, args: QueryArgs) => {
     const params: QueryCommandInput = {
       TableName: args.tableName,
       KeyConditionExpression: args.keyConditionExpression,
@@ -210,7 +210,7 @@ export function registerDynamoDBIpcHandlers(): void {
     }
   })
 
-  ipcMain.handle('dynamodb:putItem', async (_event, args: PutItemArgs) => {
+  registerValidatedHandler('dynamodb:putItem', async (_event, args: PutItemArgs) => {
     await getClient(args.region).send(
       new PutItemCommand({
         TableName: args.tableName,
@@ -220,7 +220,7 @@ export function registerDynamoDBIpcHandlers(): void {
     return null
   })
 
-  ipcMain.handle('dynamodb:deleteItem', async (_event, args: DeleteItemArgs) => {
+  registerValidatedHandler('dynamodb:deleteItem', async (_event, args: DeleteItemArgs) => {
     await getClient(args.region).send(
       new DeleteItemCommand({
         TableName: args.tableName,
@@ -230,7 +230,7 @@ export function registerDynamoDBIpcHandlers(): void {
     return null
   })
 
-  ipcMain.handle('dynamodb:getItem', async (_event, args: GetItemArgs) => {
+  registerValidatedHandler('dynamodb:getItem', async (_event, args: GetItemArgs) => {
     const response = await getClient(args.region).send(
       new GetItemCommand({
         TableName: args.tableName,

apps/desktop/src/main/env.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly MAIN_VITE_MILDSTACK_EXECUTABLE: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

apps/desktop/src/main/index.ts

@@ -5,7 +5,7 @@ import { autoUpdater } from 'electron-updater'
 import icon from '../../build/icon.png?asset'
 import { registerS3IpcHandlers } from './s3-ipc'
 import { registerDynamoDBIpcHandlers } from './dynamodb-ipc'
-import { setActiveInstancePort } from './instance-state'
+import { registerMildStackIpcHandlers } from './mildstack-ipc'
 
 // Set app name for macOS Dock and Menu Bar as early as possible
 if (process.platform === 'darwin') {
@@ -82,10 +82,7 @@ app.whenReady().then(() => {
   ipcMain.on('ping', () => console.log('pong'))
   registerS3IpcHandlers()
   registerDynamoDBIpcHandlers()
-  ipcMain.handle('instance:setSelected', (_event, port: number) => {
-    setActiveInstancePort(port)
-    return true
-  })
+  registerMildStackIpcHandlers()
 
   createWindow()
   checkForUpdates()

apps/desktop/src/main/ipc-middleware.ts

@@ -0,0 +1,62 @@
+import { ipcMain } from 'electron'
+import { getActiveInstancePort } from './instance-state'
+import { exec } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const userShell = process.env.SHELL || '/bin/zsh'
+const execAsync = (cmd: string) => promisify(exec)(cmd, { shell: userShell })
+const mildStackExecutable = import.meta.env.MAIN_VITE_MILDSTACK_EXECUTABLE || 'mildstack'
+
+/**
+ * Validates that the currently selected instance is running before
+ * allowing S3/DynamoDB commands to execute. This is called as a
+ * pre-check within IPC handlers.
+ * 
+ * Returns true if the instance is running, throws otherwise.
+ */
+export async function assertInstanceRunning(): Promise<void> {
+    const port = getActiveInstancePort()
+    try {
+        const { stdout } = await execAsync(`${mildStackExecutable} instances --json`)
+        const response = JSON.parse(stdout)
+        const instance = response.instances?.find((i: { port: number }) => i.port === port)
+
+        if (!instance) {
+            throw new Error(`No MildStack instance found on port ${port}. Please start an instance first.`)
+        }
+        if (instance.status !== 'running') {
+            throw new Error(
+                `MildStack instance on port ${port} is not running (status: ${instance.status}). Please start it first.`
+            )
+        }
+    } catch (err) {
+        if (err instanceof Error && err.message.includes('MildStack instance')) {
+            throw err
+        }
+        throw new Error(`Unable to verify MildStack instance on port ${port}. Is the CLI installed?`)
+    }
+}
+
+/**
+ * Wraps an ipcMain.handle callback with instance validation.
+ * Before the handler executes, it checks that the selected instance is running.
+ */
+export function withInstanceValidation<T extends unknown[], R>(
+    handler: (event: Electron.IpcMainInvokeEvent, ...args: T) => Promise<R>
+): (event: Electron.IpcMainInvokeEvent, ...args: T) => Promise<R> {
+    return async (event, ...args) => {
+        await assertInstanceRunning()
+        return handler(event, ...args)
+    }
+}
+
+/**
+ * Registers an IPC handler with instance validation middleware.
+ * Usage: registerValidatedHandler('channel', async (event, args) => { ... })
+ */
+export function registerValidatedHandler<T extends unknown[], R>(
+    channel: string,
+    handler: (event: Electron.IpcMainInvokeEvent, ...args: T) => Promise<R>
+): void {
+    ipcMain.handle(channel, withInstanceValidation(handler))
+}

apps/desktop/src/main/mildstack-ipc.ts

@@ -0,0 +1,145 @@
+import { ipcMain } from "electron"
+import { getActiveInstancePort, setActiveInstancePort } from "./instance-state"
+import { exec } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const userShell = process.env.SHELL || '/bin/zsh'
+const execAsync = (cmd: string) => promisify(exec)(cmd, { shell: userShell })
+
+const mildStackExecutable = import.meta.env.MAIN_VITE_MILDSTACK_EXECUTABLE || 'mildstack'
+
+export type MildStackInstanceStatus = 'running' | 'not_started' | 'errored'
+
+export interface MildStackInstance {
+    instanceId: string
+    port: number
+    pid?: number
+    status: MildStackInstanceStatus
+    error?: string
+}
+
+export interface MildStackInstancesResponse {
+    state: string
+    services: Array<{
+        name: string
+        version: string
+        tags: string[]
+    }>
+    instances: MildStackInstance[]
+    ports: number[] | null
+}
+
+/**
+ * Parses CLI error output. The CLI logs the error message on the first line
+ * and exits with status 1. execAsync rejects on non-zero exit, so we catch
+ * and extract.
+ */
+function parseCliError(err: unknown): string {
+    if (err && typeof err === 'object' && 'stderr' in err) {
+        const stderr = (err as { stderr: string }).stderr?.trim()
+        if (stderr) {
+            // First line is usually "Error: <message>"
+            const firstLine = stderr.split('\n')[0]
+            return firstLine.replace(/^Error:\s*/, '')
+        }
+    }
+    if (err && typeof err === 'object' && 'message' in err) {
+        return (err as Error).message
+    }
+    return 'Unknown CLI error'
+}
+
+export function registerMildStackIpcHandlers(): void {
+    ipcMain.handle('instance:port', async () => {
+        return getActiveInstancePort()
+    })
+
+    ipcMain.handle('instance:setSelected', (_event, port: number) => {
+        setActiveInstancePort(port)
+        return true
+    })
+
+    ipcMain.handle('mildstack:instances', async (_event): Promise<MildStackInstancesResponse> => {
+        try {
+            const { stdout } = await execAsync(`${mildStackExecutable} instances --json`)
+            return JSON.parse(stdout)
+        } catch (err) {
+            // If no instances exist or CLI is not available, return empty state
+            console.error('[MildStack IPC] instances error:', err)
+            return {
+                state: 'not_started',
+                services: [],
+                instances: [],
+                ports: null
+            }
+        }
+    })
+
+    ipcMain.handle('mildstack:serve', async (_event, port: number): Promise<{ success: boolean; error?: string }> => {
+        try {
+            // --d flag to detach (run in background)
+            await execAsync(`${mildStackExecutable} serve ${port} --d`)
+            return { success: true }
+        } catch (err) {
+            const error = parseCliError(err)
+            console.error('[MildStack IPC] serve error:', error)
+            return { success: false, error }
+        }
+    })
+
+    ipcMain.handle('mildstack:stop', async (_event, args: { port?: number; all?: boolean }): Promise<{ success: boolean; error?: string }> => {
+        try {
+            let cmd = `${mildStackExecutable} stop`
+            if (args.all) {
+                cmd += ' --all'
+            } else if (args.port) {
+                cmd += ` ${args.port}`
+            }
+            cmd += ' --json'
+            await execAsync(cmd)
+            return { success: true }
+        } catch (err) {
+            const error = parseCliError(err)
+            console.error('[MildStack IPC] stop error:', error)
+            return { success: false, error }
+        }
+    })
+
+    ipcMain.handle('mildstack:delete', async (_event, args: { port?: number; all?: boolean }): Promise<{ success: boolean; error?: string }> => {
+        try {
+            let cmd = `${mildStackExecutable} delete`
+            if (args.all) {
+                cmd += ' --all'
+            } else if (args.port) {
+                cmd += ` ${args.port}`
+            }
+            cmd += ' --json'
+            await execAsync(cmd)
+            return { success: true }
+        } catch (err) {
+            const error = parseCliError(err)
+            console.error('[MildStack IPC] delete error:', error)
+            return { success: false, error }
+        }
+    })
+
+    // Validation handler — checks if the selected instance is running
+    ipcMain.handle('mildstack:validateInstance', async (_event): Promise<{ valid: boolean; error?: string }> => {
+        const port = getActiveInstancePort()
+        try {
+            const { stdout } = await execAsync(`${mildStackExecutable} instances --json`)
+            const response: MildStackInstancesResponse = JSON.parse(stdout)
+            const instance = response.instances.find(i => i.port === port)
+
+            if (!instance) {
+                return { valid: false, error: `No instance found on port ${port}` }
+            }
+            if (instance.status !== 'running') {
+                return { valid: false, error: `Instance on port ${port} is not running (status: ${instance.status})` }
+            }
+            return { valid: true }
+        } catch {
+            return { valid: false, error: `Unable to verify instance on port ${port}` }
+        }
+    })
+}