tlc-claude-code 2.0.1 → 2.2.0

package/server/lib/docker-client.js

@@ -0,0 +1,297 @@
+/**
+ * Docker Client — wraps dockerode for Docker socket communication
+ * Phase 80 Task 1
+ */
+
+const Docker = require('dockerode');
+
+/**
+ * Create a Docker client instance
+ * @param {Object} options
+ * @param {string} [options.socketPath=/var/run/docker.sock] - Docker socket path
+ * @param {Object} [options._docker] - Injected Docker instance (for testing)
+ * @returns {Object} Docker client API
+ */
+function createDockerClient(options = {}) {
+  const socketPath = options.socketPath || '/var/run/docker.sock';
+  const docker = options._docker || new Docker({ socketPath });
+
+  /**
+   * Check if Docker daemon is accessible
+   */
+  async function isAvailable() {
+    try {
+      await docker.ping();
+      const info = await docker.version();
+      return { available: true, version: info.Version, apiVersion: info.ApiVersion };
+    } catch (err) {
+      return { available: false, error: err.message };
+    }
+  }
+
+  /**
+   * List containers
+   * @param {boolean} [all=false] - Include stopped containers
+   */
+  async function listContainers(all = false) {
+    const containers = await docker.listContainers({ all });
+    return containers.map(c => ({
+      id: c.Id,
+      name: (c.Names[0] || '').replace(/^\//, ''),
+      image: c.Image,
+      state: c.State,
+      status: c.Status,
+      ports: (c.Ports || []).map(p => ({
+        private: p.PrivatePort,
+        public: p.PublicPort,
+        type: p.Type,
+      })),
+      created: c.Created,
+      labels: c.Labels || {},
+    }));
+  }
+
+  /**
+   * Get container detail
+   * @param {string} id - Container ID or name
+   */
+  async function getContainer(id) {
+    const container = docker.getContainer(id);
+    const info = await container.inspect();
+    return {
+      id: info.Id,
+      name: (info.Name || '').replace(/^\//, ''),
+      image: info.Config.Image,
+      state: info.State.Status,
+      startedAt: info.State.StartedAt,
+      env: info.Config.Env || [],
+      mounts: (info.Mounts || []).map(m => ({
+        source: m.Source,
+        destination: m.Destination,
+        rw: m.RW,
+      })),
+      networks: info.NetworkSettings.Networks || {},
+      ports: info.HostConfig.PortBindings || {},
+    };
+  }
+
+  /**
+   * Start a container
+   * @param {string} id - Container ID
+   */
+  async function startContainer(id) {
+    const container = docker.getContainer(id);
+    await container.start();
+  }
+
+  /**
+   * Stop a container
+   * @param {string} id - Container ID
+   */
+  async function stopContainer(id) {
+    const container = docker.getContainer(id);
+    await container.stop();
+  }
+
+  /**
+   * Restart a container
+   * @param {string} id - Container ID
+   */
+  async function restartContainer(id) {
+    const container = docker.getContainer(id);
+    await container.restart();
+  }
+
+  /**
+   * Remove a container
+   * @param {string} id - Container ID
+   * @param {boolean} [force=false] - Force removal
+   */
+  async function removeContainer(id, force = false) {
+    const container = docker.getContainer(id);
+    await container.remove({ force });
+  }
+
+  /**
+   * Get container stats snapshot
+   * @param {string} id - Container ID
+   */
+  async function getContainerStats(id) {
+    const container = docker.getContainer(id);
+    const stats = await container.stats({ stream: false });
+
+    // Calculate CPU %
+    const cpuDelta = (stats.cpu_stats?.cpu_usage?.total_usage || 0) - (stats.precpu_stats?.cpu_usage?.total_usage || 0);
+    const systemDelta = (stats.cpu_stats?.system_cpu_usage || 0) - (stats.precpu_stats?.system_cpu_usage || 0);
+    const numCpus = stats.cpu_stats?.online_cpus || 1;
+    const cpuPercent = systemDelta > 0 ? (cpuDelta / systemDelta) * numCpus * 100 : 0;
+
+    // Memory
+    const cache = stats.memory_stats?.stats?.cache || stats.memory_stats?.stats?.inactive_file || 0;
+    const memoryUsage = (stats.memory_stats?.usage || 0) - cache;
+    const memoryLimit = stats.memory_stats?.limit || 0;
+
+    // Network
+    let networkRx = 0;
+    let networkTx = 0;
+    if (stats.networks) {
+      for (const iface of Object.values(stats.networks)) {
+        networkRx += iface.rx_bytes || 0;
+        networkTx += iface.tx_bytes || 0;
+      }
+    }
+
+    return { cpuPercent, memoryUsage, memoryLimit, networkRx, networkTx };
+  }
+
+  /**
+   * Get container logs
+   * @param {string} id - Container ID
+   * @param {Object} [opts]
+   * @param {number} [opts.tail=100] - Number of lines
+   */
+  async function getContainerLogs(id, opts = {}) {
+    const container = docker.getContainer(id);
+    const logs = await container.logs({
+      stdout: true,
+      stderr: true,
+      tail: opts.tail || 100,
+      timestamps: true,
+    });
+    // logs may be Buffer or string
+    return typeof logs === 'string' ? logs : logs.toString('utf8');
+  }
+
+  /**
+   * Stream container logs (live)
+   * @param {string} id - Container ID
+   * @param {Function} callback - Called with each log chunk
+   * @returns {Function} abort function
+   */
+  function streamContainerLogs(id, callback) {
+    let aborted = false;
+    let streamRef = null;
+    const container = docker.getContainer(id);
+    container.logs({ follow: true, stdout: true, stderr: true, tail: 50, timestamps: true })
+      .then(stream => {
+        streamRef = stream;
+        if (aborted) { stream.destroy && stream.destroy(); return; }
+        stream.on('data', chunk => {
+          if (!aborted) callback(chunk.toString('utf8'));
+        });
+        stream.on('end', () => {});
+      })
+      .catch((err) => { callback && callback(null, err); });
+    return () => { aborted = true; if (streamRef) { streamRef.destroy && streamRef.destroy(); } };
+  }
+
+  /**
+   * Stream container stats (live)
+   * @param {string} id - Container ID
+   * @param {Function} callback - Called with each stats update
+   * @returns {Function} abort function
+   */
+  function streamContainerStats(id, callback) {
+    let aborted = false;
+    let streamRef = null;
+    const container = docker.getContainer(id);
+    container.stats({ stream: true })
+      .then(stream => {
+        streamRef = stream;
+        if (aborted) { stream.destroy && stream.destroy(); return; }
+        let buffer = '';
+        stream.on('data', chunk => {
+          if (aborted) { stream.destroy(); return; }
+          buffer += chunk.toString('utf8');
+          const lines = buffer.split('\n');
+          buffer = lines.pop();
+          for (const line of lines) {
+            if (line.trim()) {
+              try {
+                const stats = JSON.parse(line);
+                const cpuDelta = (stats.cpu_stats?.cpu_usage?.total_usage || 0) - (stats.precpu_stats?.cpu_usage?.total_usage || 0);
+                const systemDelta = (stats.cpu_stats?.system_cpu_usage || 0) - (stats.precpu_stats?.system_cpu_usage || 0);
+                const numCpus = stats.cpu_stats?.online_cpus || 1;
+                callback({
+                  cpuPercent: systemDelta > 0 ? (cpuDelta / systemDelta) * numCpus * 100 : 0,
+                  memoryUsage: stats.memory_stats?.usage || 0,
+                  memoryLimit: stats.memory_stats?.limit || 0,
+                });
+              } catch {}
+            }
+          }
+        });
+      })
+      .catch((err) => { callback && callback(null, err); });
+    return () => { aborted = true; if (streamRef) { streamRef.destroy && streamRef.destroy(); } };
+  }
+
+  /**
+   * List images
+   */
+  async function listImages() {
+    const images = await docker.listImages();
+    return images.map(img => ({
+      id: img.Id,
+      tags: img.RepoTags || [],
+      size: img.Size,
+      created: img.Created,
+    }));
+  }
+
+  /**
+   * List volumes
+   */
+  async function listVolumes() {
+    const result = await docker.listVolumes();
+    return (result.Volumes || []).map(v => ({
+      name: v.Name,
+      driver: v.Driver,
+      mountpoint: v.Mountpoint,
+      createdAt: v.CreatedAt,
+    }));
+  }
+
+  /**
+   * Match a container to a TLC project by name or labels
+   * @param {Object} container - { name, labels }
+   * @param {Array} projects - [{ name, path }]
+   * @returns {string|null} matched project name or null
+   */
+  function matchContainerToProject(container, projects) {
+    // Match by compose project label
+    const composeProject = container.labels && container.labels['com.docker.compose.project'];
+    if (composeProject) {
+      const match = projects.find(p => p.name.toLowerCase() === composeProject.toLowerCase());
+      if (match) return match.name;
+    }
+
+    // Match by container name containing project name
+    const cName = (container.name || '').toLowerCase();
+    for (const project of projects) {
+      const pName = project.name.toLowerCase();
+      if (cName.includes(pName)) return project.name;
+    }
+
+    return null;
+  }
+
+  return {
+    isAvailable,
+    listContainers,
+    getContainer,
+    startContainer,
+    stopContainer,
+    restartContainer,
+    removeContainer,
+    getContainerStats,
+    getContainerLogs,
+    streamContainerLogs,
+    streamContainerStats,
+    listImages,
+    listVolumes,
+    matchContainerToProject,
+  };
+}
+
+module.exports = { createDockerClient };

package/server/lib/docker-client.test.js

@@ -0,0 +1,308 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+const { createDockerClient } = await import('./docker-client.js');
+
+/**
+ * Create a mock dockerode instance for injection
+ */
+function createMockDocker() {
+  const mockContainer = {
+    inspect: vi.fn(),
+    start: vi.fn(),
+    stop: vi.fn(),
+    restart: vi.fn(),
+    remove: vi.fn(),
+    stats: vi.fn(),
+    logs: vi.fn(),
+  };
+
+  const mockDocker = {
+    listContainers: vi.fn(),
+    getContainer: vi.fn(() => mockContainer),
+    listImages: vi.fn(),
+    listVolumes: vi.fn(),
+    ping: vi.fn(),
+    version: vi.fn(),
+    getEvents: vi.fn(),
+  };
+
+  return { mockDocker, mockContainer };
+}
+
+describe('DockerClient', () => {
+  let client;
+  let mockDocker;
+  let mockContainer;
+
+  beforeEach(() => {
+    const mocks = createMockDocker();
+    mockDocker = mocks.mockDocker;
+    mockContainer = mocks.mockContainer;
+    client = createDockerClient({ _docker: mockDocker });
+    vi.clearAllMocks();
+  });
+
+  describe('isAvailable', () => {
+    it('returns true when Docker socket is accessible', async () => {
+      mockDocker.ping.mockResolvedValue('OK');
+      mockDocker.version.mockResolvedValue({ Version: '24.0.0', ApiVersion: '1.43' });
+
+      const result = await client.isAvailable();
+      expect(result).toEqual({
+        available: true,
+        version: '24.0.0',
+        apiVersion: '1.43',
+      });
+    });
+
+    it('returns false when Docker socket is missing', async () => {
+      mockDocker.ping.mockRejectedValue(new Error('connect ENOENT /var/run/docker.sock'));
+
+      const result = await client.isAvailable();
+      expect(result).toEqual({
+        available: false,
+        error: expect.stringContaining('ENOENT'),
+      });
+    });
+  });
+
+  describe('listContainers', () => {
+    it('returns formatted container objects', async () => {
+      mockDocker.listContainers.mockResolvedValue([
+        {
+          Id: 'abc123def456',
+          Names: ['/tlc-dev-dashboard'],
+          Image: 'node:20-alpine',
+          State: 'running',
+          Status: 'Up 2 hours',
+          Ports: [{ PrivatePort: 3147, PublicPort: 3147, Type: 'tcp' }],
+          Created: 1708300000,
+          Labels: { 'com.docker.compose.project': 'tlc' },
+        },
+      ]);
+
+      const containers = await client.listContainers();
+      expect(containers).toHaveLength(1);
+      expect(containers[0]).toEqual({
+        id: 'abc123def456',
+        name: 'tlc-dev-dashboard',
+        image: 'node:20-alpine',
+        state: 'running',
+        status: 'Up 2 hours',
+        ports: [{ private: 3147, public: 3147, type: 'tcp' }],
+        created: 1708300000,
+        labels: { 'com.docker.compose.project': 'tlc' },
+      });
+    });
+
+    it('lists all containers including stopped when all=true', async () => {
+      mockDocker.listContainers.mockResolvedValue([]);
+      await client.listContainers(true);
+      expect(mockDocker.listContainers).toHaveBeenCalledWith({ all: true });
+    });
+
+    it('lists only running containers by default', async () => {
+      mockDocker.listContainers.mockResolvedValue([]);
+      await client.listContainers();
+      expect(mockDocker.listContainers).toHaveBeenCalledWith({ all: false });
+    });
+  });
+
+  describe('getContainer', () => {
+    it('returns full detail for valid container ID', async () => {
+      mockContainer.inspect.mockResolvedValue({
+        Id: 'abc123',
+        Name: '/tlc-dev-dashboard',
+        Config: {
+          Image: 'node:20-alpine',
+          Env: ['NODE_ENV=development', 'TLC_PORT=3147'],
+        },
+        State: { Status: 'running', StartedAt: '2026-02-18T00:00:00Z' },
+        Mounts: [{ Source: '/home/user/tlc', Destination: '/tlc', RW: true }],
+        NetworkSettings: { Networks: { bridge: { IPAddress: '172.17.0.2' } } },
+        HostConfig: { PortBindings: { '3147/tcp': [{ HostPort: '3147' }] } },
+      });
+
+      const detail = await client.getContainer('abc123');
+      expect(detail.id).toBe('abc123');
+      expect(detail.name).toBe('tlc-dev-dashboard');
+      expect(detail.image).toBe('node:20-alpine');
+      expect(detail.state).toBe('running');
+      expect(detail.env).toContain('NODE_ENV=development');
+      expect(detail.mounts).toHaveLength(1);
+      expect(detail.mounts[0].source).toBe('/home/user/tlc');
+    });
+
+    it('throws for non-existent container', async () => {
+      mockContainer.inspect.mockRejectedValue(
+        Object.assign(new Error('no such container'), { statusCode: 404 })
+      );
+      await expect(client.getContainer('nonexistent')).rejects.toThrow('no such container');
+    });
+  });
+
+  describe('startContainer', () => {
+    it('calls dockerode start', async () => {
+      mockContainer.start.mockResolvedValue();
+      await client.startContainer('abc123');
+      expect(mockDocker.getContainer).toHaveBeenCalledWith('abc123');
+      expect(mockContainer.start).toHaveBeenCalled();
+    });
+  });
+
+  describe('stopContainer', () => {
+    it('calls dockerode stop', async () => {
+      mockContainer.stop.mockResolvedValue();
+      await client.stopContainer('abc123');
+      expect(mockDocker.getContainer).toHaveBeenCalledWith('abc123');
+      expect(mockContainer.stop).toHaveBeenCalled();
+    });
+  });
+
+  describe('restartContainer', () => {
+    it('calls dockerode restart', async () => {
+      mockContainer.restart.mockResolvedValue();
+      await client.restartContainer('abc123');
+      expect(mockDocker.getContainer).toHaveBeenCalledWith('abc123');
+      expect(mockContainer.restart).toHaveBeenCalled();
+    });
+  });
+
+  describe('removeContainer', () => {
+    it('removes container with force option', async () => {
+      mockContainer.remove.mockResolvedValue();
+      await client.removeContainer('abc123', true);
+      expect(mockContainer.remove).toHaveBeenCalledWith({ force: true });
+    });
+
+    it('removes container without force by default', async () => {
+      mockContainer.remove.mockResolvedValue();
+      await client.removeContainer('abc123');
+      expect(mockContainer.remove).toHaveBeenCalledWith({ force: false });
+    });
+  });
+
+  describe('getContainerStats', () => {
+    it('calculates CPU percentage from raw stats', async () => {
+      mockContainer.stats.mockResolvedValue({
+        cpu_stats: {
+          cpu_usage: { total_usage: 500000000 },
+          system_cpu_usage: 10000000000,
+          online_cpus: 4,
+        },
+        precpu_stats: {
+          cpu_usage: { total_usage: 400000000 },
+          system_cpu_usage: 9000000000,
+        },
+        memory_stats: {
+          usage: 104857600,
+          limit: 2147483648,
+          stats: { cache: 10485760 },
+        },
+        networks: {
+          eth0: { rx_bytes: 1024000, tx_bytes: 512000 },
+        },
+      });
+
+      const stats = await client.getContainerStats('abc123');
+      expect(stats.cpuPercent).toBeGreaterThan(0);
+      expect(stats.memoryUsage).toBeGreaterThan(0);
+      expect(stats.memoryLimit).toBe(2147483648);
+      expect(stats.networkRx).toBe(1024000);
+      expect(stats.networkTx).toBe(512000);
+    });
+  });
+
+  describe('getContainerLogs', () => {
+    it('returns recent log lines', async () => {
+      const mockStream = Buffer.from('line1\nline2\nline3\n');
+      mockContainer.logs.mockResolvedValue(mockStream);
+
+      const logs = await client.getContainerLogs('abc123', { tail: 100 });
+      expect(mockContainer.logs).toHaveBeenCalledWith({
+        stdout: true,
+        stderr: true,
+        tail: 100,
+        timestamps: true,
+      });
+      expect(typeof logs).toBe('string');
+    });
+  });
+
+  describe('listImages', () => {
+    it('returns formatted image objects', async () => {
+      mockDocker.listImages.mockResolvedValue([
+        {
+          Id: 'sha256:abc123',
+          RepoTags: ['node:20-alpine'],
+          Size: 180000000,
+          Created: 1708200000,
+        },
+      ]);
+
+      const images = await client.listImages();
+      expect(images).toHaveLength(1);
+      expect(images[0]).toEqual({
+        id: 'sha256:abc123',
+        tags: ['node:20-alpine'],
+        size: 180000000,
+        created: 1708200000,
+      });
+    });
+  });
+
+  describe('listVolumes', () => {
+    it('returns formatted volume objects', async () => {
+      mockDocker.listVolumes.mockResolvedValue({
+        Volumes: [
+          {
+            Name: 'postgres-data',
+            Driver: 'local',
+            Mountpoint: '/var/lib/docker/volumes/postgres-data/_data',
+            CreatedAt: '2026-02-18T00:00:00Z',
+          },
+        ],
+      });
+
+      const volumes = await client.listVolumes();
+      expect(volumes).toHaveLength(1);
+      expect(volumes[0]).toEqual({
+        name: 'postgres-data',
+        driver: 'local',
+        mountpoint: '/var/lib/docker/volumes/postgres-data/_data',
+        createdAt: '2026-02-18T00:00:00Z',
+      });
+    });
+  });
+
+  describe('matchContainerToProject', () => {
+    it('matches by container name pattern', () => {
+      const container = { name: 'tlc-myapp-dashboard', labels: {} };
+      const projects = [
+        { name: 'myapp', path: '/home/user/myapp' },
+        { name: 'other', path: '/home/user/other' },
+      ];
+      const match = client.matchContainerToProject(container, projects);
+      expect(match).toBe('myapp');
+    });
+
+    it('matches by compose project label', () => {
+      const container = {
+        name: 'some-random-name',
+        labels: { 'com.docker.compose.project': 'myapp' },
+      };
+      const projects = [
+        { name: 'myapp', path: '/home/user/myapp' },
+      ];
+      const match = client.matchContainerToProject(container, projects);
+      expect(match).toBe('myapp');
+    });
+
+    it('returns null when no match found', () => {
+      const container = { name: 'unrelated-container', labels: {} };
+      const projects = [{ name: 'myapp', path: '/home/user/myapp' }];
+      const match = client.matchContainerToProject(container, projects);
+      expect(match).toBeNull();
+    });
+  });
+});

package/server/lib/input-sanitizer.js

@@ -0,0 +1,86 @@
+/**
+ * Input Sanitizer — validation for user-supplied values used in shell commands
+ * Phase 80 Review Fix
+ */
+
+/** Strict DNS hostname pattern */
+const DOMAIN_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
+
+/** Safe git branch pattern (allows slashes, dots, dashes, underscores) */
+const BRANCH_RE = /^[a-zA-Z0-9._\/-]+$/;
+
+/** Safe git repo URL pattern (git@... or https://...) */
+const REPO_URL_RE = /^(git@[\w.-]+:[\w./-]+\.git|https?:\/\/[\w.-]+(\/[\w./-]+)*(\.git)?)$/;
+
+/** Safe unix username pattern */
+const USERNAME_RE = /^[a-z_][a-z0-9_-]*$/;
+
+/** Safe project name pattern */
+const PROJECT_NAME_RE = /^[a-zA-Z0-9._-]+$/;
+
+/**
+ * Validate a DNS hostname/domain
+ * @param {string} domain
+ * @returns {boolean}
+ */
+function isValidDomain(domain) {
+  if (!domain || typeof domain !== 'string') return false;
+  if (domain.length > 253) return false;
+  return DOMAIN_RE.test(domain);
+}
+
+/**
+ * Validate a git branch name
+ * @param {string} branch
+ * @returns {boolean}
+ */
+function isValidBranch(branch) {
+  if (!branch || typeof branch !== 'string') return false;
+  if (branch.length > 255) return false;
+  if (branch.includes('..')) return false;
+  return BRANCH_RE.test(branch);
+}
+
+/**
+ * Validate a git repo URL
+ * @param {string} url
+ * @returns {boolean}
+ */
+function isValidRepoUrl(url) {
+  if (!url || typeof url !== 'string') return false;
+  return REPO_URL_RE.test(url);
+}
+
+/**
+ * Validate a unix username
+ * @param {string} username
+ * @returns {boolean}
+ */
+function isValidUsername(username) {
+  if (!username || typeof username !== 'string') return false;
+  if (username.length > 32) return false;
+  return USERNAME_RE.test(username);
+}
+
+/**
+ * Validate a project name (used in file paths)
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isValidProjectName(name) {
+  if (!name || typeof name !== 'string') return false;
+  if (name.length > 128) return false;
+  if (name.includes('..') || name.includes('/')) return false;
+  return PROJECT_NAME_RE.test(name);
+}
+
+module.exports = {
+  isValidDomain,
+  isValidBranch,
+  isValidRepoUrl,
+  isValidUsername,
+  isValidProjectName,
+  DOMAIN_RE,
+  BRANCH_RE,
+  REPO_URL_RE,
+};