feat: docker run to compose converter (#623)

* feat(convert): harden /api/convert endpoint with auth, validation, and tests

Applies authMiddleware to the docker run to compose endpoint, validates
that the payload is a non-empty string within an 8192 character budget,
rejects inputs containing null bytes, and wraps composerize in a
try/catch that surfaces a 422 with a clear message when the library
cannot produce a services block. Adds a Vitest suite covering the auth
gate, happy path, common flag coverage, boundary and null byte
placement variants, and malformed command handling.

* feat(editor): add From Docker Run tab to create stack dialog

Introduces a third tab in the Create New Stack dialog that accepts a
docker run command, calls the converter endpoint, and previews the
returned compose YAML before writing it to a new stack directory. Uses
the defensive toast pattern, clears the stale preview when the input
changes, and rolls back the empty stack directory if saving the
converted YAML fails so the user never ends up with an orphan stack.

* docs(stack-management): document docker run to compose converter

Adds a Convert from a docker run command section to the stack
management page covering how to use the new tab, the list of supported
flags, and troubleshooting for unparseable inputs. Screenshots show the
empty tab, a successful conversion with the compose preview, the
resulting stack in the editor, and the error toast surfaced when the
input cannot be converted. Appends a matching entry to the
troubleshooting page.

backend/src/__tests__/convert.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Tests for the authenticated `POST /api/convert` endpoint that wraps the
+ * composerize library. Verifies input validation, auth gating, graceful
+ * handling of malformed commands, and output shape.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import request from 'supertest';
+import { setupTestDb, cleanupTestDb, loginAsTestAdmin } from './helpers/setupTestDb';
+
+let tmpDir: string;
+let app: import('express').Express;
+let cookie: string;
+
+beforeAll(async () => {
+  tmpDir = await setupTestDb();
+  ({ app } = await import('../index'));
+  cookie = await loginAsTestAdmin(app);
+});
+
+afterAll(() => {
+  cleanupTestDb(tmpDir);
+});
+
+describe('POST /api/convert', () => {
+  describe('auth', () => {
+    it('rejects unauthenticated requests with 401', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .send({ dockerRun: 'docker run nginx' });
+      expect(res.status).toBe(401);
+    });
+  });
+
+  describe('happy path', () => {
+    it('converts a simple docker run command', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: 'docker run nginx' });
+      expect(res.status).toBe(200);
+      expect(typeof res.body.yaml).toBe('string');
+      expect(res.body.yaml).toContain('services:');
+      expect(res.body.yaml).toContain('nginx');
+    });
+
+    it('handles common flags (-p, -v, -e, --name, --restart)', async () => {
+      const cmd =
+        'docker run -d --name web -p 8080:80 -v /data:/usr/share/nginx/html -e TZ=UTC --restart unless-stopped nginx:alpine';
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: cmd });
+      expect(res.status).toBe(200);
+      expect(res.body.yaml).toContain('services:');
+      expect(res.body.yaml).toContain('web');
+      expect(res.body.yaml).toContain('nginx:alpine');
+      expect(res.body.yaml).toContain('8080:80');
+    });
+
+    it('handles --label and --network flags', async () => {
+      const cmd =
+        'docker run --name api --label com.example.app=api --network bridge redis:7';
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: cmd });
+      expect(res.status).toBe(200);
+      expect(res.body.yaml).toContain('services:');
+      expect(res.body.yaml).toContain('redis:7');
+    });
+
+    it('trims surrounding whitespace', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: '  \n  docker run nginx  \n ' });
+      expect(res.status).toBe(200);
+      expect(res.body.yaml).toContain('services:');
+    });
+  });
+
+  describe('input validation', () => {
+    it('rejects missing body', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({});
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/string/i);
+    });
+
+    it('rejects empty string', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: '' });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/required/i);
+    });
+
+    it('rejects whitespace-only input', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: '   \n\t  ' });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/required/i);
+    });
+
+    it('rejects non-string input', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: 12345 });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/string/i);
+    });
+
+    it('accepts input at the 8192-char boundary', async () => {
+      const prefix = 'docker run nginx ';
+      const filler = 'a'.repeat(8192 - prefix.length);
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: prefix + filler });
+      // Either composerize accepts (200) or rejects as unparseable (422), but never
+      // a 400 "too long" at exactly the max length.
+      expect([200, 422]).toContain(res.status);
+    });
+
+    it('rejects input one byte over the 8192-char boundary', async () => {
+      const prefix = 'docker run nginx ';
+      const filler = 'a'.repeat(8193 - prefix.length);
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: prefix + filler });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/too long/i);
+    });
+
+    it('rejects oversized input (>8192 chars)', async () => {
+      const big = 'docker run ' + 'x'.repeat(9000);
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: big });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/too long/i);
+    });
+
+    it('rejects input with a trailing null byte', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: 'docker run nginx\0' });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/invalid/i);
+    });
+
+    it('rejects input with a leading null byte', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: '\0docker run nginx' });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/invalid/i);
+    });
+
+    it('rejects input with an embedded null byte', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: 'docker run \0nginx' });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/invalid/i);
+    });
+  });
+
+  describe('malformed commands', () => {
+    it('returns 422 when composerize cannot produce services', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: 'this is not a docker run command' });
+      expect(res.status).toBe(422);
+      expect(res.body.error).toMatch(/parse|supported/i);
+    });
+
+    it('returns 422 for pure gibberish', async () => {
+      const res = await request(app)
+        .post('/api/convert')
+        .set('Cookie', cookie)
+        .send({ dockerRun: '!!!@@@###$$$' });
+      expect(res.status).toBe(422);
+    });
+  });
+});

backend/src/index.ts

@@ -4947,19 +4947,47 @@ app.get('/api/stacks/:stackName/backup', async (req: Request, res: Response) =>
   }
 });
 
-// Docker Run to Compose converter endpoint
-app.post('/api/convert', async (req: Request, res: Response) => {
+// Docker Run to Compose converter endpoint.
+// Accepts a raw `docker run ...` command and returns the equivalent compose
+// YAML as a string. Authenticated, input-validated, and resilient to
+// composerize throws / malformed output.
+const MAX_DOCKER_RUN_LENGTH = 8192;
+app.post('/api/convert', authMiddleware, async (req: Request, res: Response): Promise<void> => {
+  const { dockerRun } = req.body ?? {};
+  if (typeof dockerRun !== 'string') {
+    res.status(400).json({ error: 'dockerRun must be a string' });
+    return;
+  }
+  const trimmed = dockerRun.trim();
+  if (trimmed.length === 0) {
+    res.status(400).json({ error: 'dockerRun command is required' });
+    return;
+  }
+  if (trimmed.length > MAX_DOCKER_RUN_LENGTH) {
+    res.status(400).json({ error: `dockerRun command is too long (max ${MAX_DOCKER_RUN_LENGTH} characters)` });
+    return;
+  }
+  if (trimmed.includes('\0')) {
+    res.status(400).json({ error: 'dockerRun command contains invalid characters' });
+    return;
+  }
+
+  let yaml: unknown;
   try {
-    const { dockerRun } = req.body;
-    if (!dockerRun || typeof dockerRun !== 'string') {
-      return res.status(400).json({ error: 'dockerRun command is required' });
-    }
-    const yaml = composerize(dockerRun);
-    res.json({ yaml });
+    yaml = composerize(trimmed);
   } catch (error) {
     console.error('Conversion error:', error);
-    res.status(500).json({ error: 'Failed to convert docker run command' });
+    res.status(422).json({ error: 'Could not parse command. Check syntax and supported flags.' });
+    return;
   }
+
+  if (typeof yaml !== 'string' || !yaml.includes('services:')) {
+    console.warn('Converter produced unexpected output for input:', trimmed.slice(0, 200));
+    res.status(422).json({ error: 'Could not parse command. Check syntax and supported flags.' });
+    return;
+  }
+
+  res.json({ yaml });
 });
 
 // Get all containers stats for dashboard.