@elyracode/docker 0.5.12

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.5.11] - 2026-05-16
+
+## [0.5.10] - 2026-05-15
+
+### Added
+- Initial release
+- `docker_exec` tool: run commands inside containers
+- `docker_logs` tool: tail container logs with grep filtering
+- `docker_status` tool: running containers, resource usage, ports
+- `docker_compose` tool: up/down/restart/build operations
+- `docker_env_check` tool: compare host .env with container environment
+- `/docker` command for container status dashboard
+- Auto-injects compose context into system prompt on session start
+- Skill file for automatic Docker tool selection

package/README.md

@@ -0,0 +1,85 @@
+# @elyracode/docker
+
+Docker-aware development for Elyra. Container exec routing, log tailing, compose operations, environment sync checks, and container health monitoring.
+
+## Install
+
+```
+elyra install npm:@elyracode/docker
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `docker_exec` | Run a command inside a Docker container |
+| `docker_logs` | Read recent logs from a container |
+| `docker_status` | List running containers with resource usage, ports, and health |
+| `docker_compose` | Run docker compose operations (up, down, restart, build) |
+| `docker_env_check` | Compare host .env with container environment variables |
+
+## Commands
+
+- `/docker` -- Container status dashboard (running containers, ports, health)
+
+## Usage
+
+### Container execution
+
+The agent automatically routes commands through `docker exec` when it detects a Docker environment:
+
+```
+> Run the database migrations
+> Run the test suite
+> Check the PHP version in the app container
+```
+
+Or be explicit:
+
+```
+> Run "php artisan migrate" in the app container
+> Execute "npm run build" in the node container
+```
+
+### Log reading
+
+```
+> Show me the last 50 lines of the app container logs
+> What errors are in the nginx logs?
+> Tail the database logs and look for slow queries
+```
+
+### Compose operations
+
+```
+> Rebuild the app container
+> Restart the database service
+> Bring up the entire stack
+> Shut down all containers
+```
+
+### Environment sync
+
+```
+> Check if my .env matches what the app container sees
+> Compare environment variables between host and container
+```
+
+### Status
+
+```
+/docker
+```
+
+Shows running containers, CPU/memory usage, port mappings, volume mounts, and health check status.
+
+## How it works
+
+On session start, the extension reads `docker-compose.yml` (or `compose.yml`) and injects container context into the system prompt. The agent knows which services exist, which ports are mapped, and which volumes are mounted.
+
+When commands need to run inside a container, `docker_exec` handles the routing. The agent doesn't need to be told "use docker exec" -- it knows from context.
+
+## Requirements
+
+- Docker CLI installed and running
+- Docker Compose v2 (for compose operations)

package/extensions/index.ts

@@ -0,0 +1,461 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { Type } from "typebox";
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function exec(cmd: string, cwd?: string, timeoutMs = 15000): string {
+	try {
+		return execSync(cmd, {
+			cwd,
+			encoding: "utf-8",
+			timeout: timeoutMs,
+			maxBuffer: 1024 * 1024,
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+	} catch (error: any) {
+		const stderr = error.stderr?.toString().trim() ?? "";
+		const stdout = error.stdout?.toString().trim() ?? "";
+		return stderr || stdout || error.message;
+	}
+}
+
+function dockerAvailable(): boolean {
+	try {
+		execSync("docker info", { stdio: "pipe", timeout: 5000 });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function findComposeFile(cwd: string): string | undefined {
+	const candidates = ["docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"];
+	for (const name of candidates) {
+		if (existsSync(join(cwd, name))) return name;
+	}
+	return undefined;
+}
+
+function getRunningContainers(cwd?: string): string {
+	return exec(
+		'docker ps --format "{{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"',
+		cwd,
+	);
+}
+
+// ── Extension ───────────────────────────────────────────────────────────────
+
+export default function (elyra: ExtensionAPI): void {
+	// Inject Docker context into system prompt on session start
+	elyra.on("before_agent_start", async (_event, ctx) => {
+		const cwd = ctx.cwd;
+		if (!dockerAvailable()) return;
+
+		const composeFile = findComposeFile(cwd);
+		if (!composeFile) return;
+
+		const composeContent = readFileSync(join(cwd, composeFile), "utf-8");
+		const running = getRunningContainers(cwd);
+
+		const contextBlock =
+			`## Docker Environment\n\n` +
+			`Compose file: ${composeFile}\n` +
+			`\`\`\`yaml\n${composeContent}\n\`\`\`\n\n` +
+			(running
+				? `Running containers:\n\`\`\`\n${running}\n\`\`\`\n\n`
+				: "No containers currently running.\n\n") +
+			`When running commands (migrations, tests, builds), use docker_exec to route them ` +
+			`to the appropriate container instead of running on the host.`;
+
+		const currentPrompt = ctx.getSystemPrompt();
+		return {
+			systemPrompt: currentPrompt + "\n\n" + contextBlock,
+		};
+	});
+
+	// ── Tool: docker_exec ───────────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "docker_exec",
+		label: "Docker Exec",
+		description:
+			"Run a command inside a Docker container. Use this instead of bash when the project " +
+			"uses Docker and the command should run in the container environment (e.g., migrations, " +
+			"tests, package installs, artisan commands). Detects the right container from the service name.",
+		parameters: Type.Object({
+			container: Type.String({
+				description:
+					"Container or service name (e.g., 'app', 'node', 'web', 'php'). " +
+					"Use docker_status to list running containers if unsure.",
+			}),
+			command: Type.String({
+				description: "Command to execute inside the container",
+			}),
+			workdir: Type.Optional(
+				Type.String({
+					description: "Working directory inside the container (e.g., /var/www/html)",
+				}),
+			),
+			user: Type.Optional(
+				Type.String({
+					description: "User to run as inside the container (e.g., 'www-data', 'node')",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			if (!dockerAvailable()) {
+				return {
+					content: [{ type: "text", text: "Docker is not running or not installed." }],
+					details: {},
+				};
+			}
+
+			const parts = ["docker exec"];
+			if (params.workdir) parts.push(`-w "${params.workdir}"`);
+			if (params.user) parts.push(`-u "${params.user}"`);
+			parts.push(params.container);
+			parts.push(params.command);
+
+			const cmd = parts.join(" ");
+			const output = exec(cmd, undefined, 60000);
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: `$ ${cmd}\n\n${output || "(no output)"}`,
+					},
+				],
+				details: { container: params.container, command: params.command },
+			};
+		},
+	});
+
+	// ── Tool: docker_logs ───────────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "docker_logs",
+		label: "Docker Logs",
+		description:
+			"Read recent logs from a Docker container. Use this to diagnose errors, " +
+			"check application output, or monitor service behavior. " +
+			"Always check logs before debugging -- the answer is often there.",
+		parameters: Type.Object({
+			container: Type.String({
+				description: "Container or service name",
+			}),
+			tail: Type.Optional(
+				Type.Number({
+					description: "Number of lines to show (default: 100)",
+				}),
+			),
+			since: Type.Optional(
+				Type.String({
+					description: "Show logs since timestamp or duration (e.g., '10m', '1h', '2024-01-01')",
+				}),
+			),
+			grep: Type.Optional(
+				Type.String({
+					description: "Filter logs by pattern (grep)",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			if (!dockerAvailable()) {
+				return {
+					content: [{ type: "text", text: "Docker is not running or not installed." }],
+					details: {},
+				};
+			}
+
+			const tail = params.tail ?? 100;
+			let cmd = `docker logs --tail ${tail}`;
+			if (params.since) cmd += ` --since "${params.since}"`;
+			cmd += ` ${params.container}`;
+			if (params.grep) cmd += ` 2>&1 | grep -i "${params.grep}"`;
+
+			const output = exec(cmd, undefined, 15000);
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: output || "(no logs)",
+					},
+				],
+				details: { container: params.container, lines: tail },
+			};
+		},
+	});
+
+	// ── Tool: docker_status ─────────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "docker_status",
+		label: "Docker Status",
+		description:
+			"List running Docker containers with status, ports, and resource usage. " +
+			"Use this to check what's running, find container names, and verify health.",
+		parameters: Type.Object({}),
+		execute: async () => {
+			if (!dockerAvailable()) {
+				return {
+					content: [{ type: "text", text: "Docker is not running or not installed." }],
+					details: {},
+				};
+			}
+
+			const ps = exec(
+				'docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}\t{{.Size}}"',
+			);
+
+			// Get resource usage
+			let stats = "";
+			try {
+				stats = exec(
+					'docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}"',
+					undefined,
+					10000,
+				);
+			} catch {
+				// stats might timeout on slow systems
+			}
+
+			const parts = ["# Docker Status\n"];
+			parts.push("## Running Containers\n```\n" + (ps || "No containers running") + "\n```\n");
+			if (stats) {
+				parts.push("## Resource Usage\n```\n" + stats + "\n```\n");
+			}
+
+			return {
+				content: [{ type: "text", text: parts.join("\n") }],
+				details: {},
+			};
+		},
+	});
+
+	// ── Tool: docker_compose ────────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "docker_compose",
+		label: "Docker Compose",
+		description:
+			"Run docker compose operations: up, down, restart, build, pull. " +
+			"Use this to manage the container stack -- start services, rebuild after " +
+			"Dockerfile changes, restart after config changes.",
+		parameters: Type.Object({
+			action: Type.String({
+				description: "Compose action: up, down, restart, build, pull, ps",
+			}),
+			service: Type.Optional(
+				Type.String({
+					description: "Target specific service (e.g., 'app', 'db'). Omit for all services.",
+				}),
+			),
+			flags: Type.Optional(
+				Type.String({
+					description: "Additional flags (e.g., '-d' for detached, '--build' for up with build)",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			if (!dockerAvailable()) {
+				return {
+					content: [{ type: "text", text: "Docker is not running or not installed." }],
+					details: {},
+				};
+			}
+
+			const allowed = ["up", "down", "restart", "build", "pull", "ps", "stop", "start"];
+			if (!allowed.includes(params.action)) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Action "${params.action}" not allowed. Use: ${allowed.join(", ")}`,
+						},
+					],
+					details: {},
+				};
+			}
+
+			let cmd = `docker compose ${params.action}`;
+			if (params.flags) cmd += ` ${params.flags}`;
+			if (params.service) cmd += ` ${params.service}`;
+
+			// Add -d for up if not specified
+			if (params.action === "up" && !params.flags?.includes("-d")) {
+				cmd = `docker compose up -d${params.service ? ` ${params.service}` : ""}`;
+			}
+
+			const cwd = process.cwd();
+			const output = exec(cmd, cwd, 120000);
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: `$ ${cmd}\n\n${output || "(done)"}`,
+					},
+				],
+				details: { action: params.action, service: params.service },
+			};
+		},
+	});
+
+	// ── Tool: docker_env_check ──────────────────────────────────────────────
+
+	elyra.registerTool({
+		name: "docker_env_check",
+		label: "Docker Env Check",
+		description:
+			"Compare host .env file with the actual environment variables inside a container. " +
+			"Finds mismatches that cause 'works on my machine' bugs: missing vars, different values, " +
+			"vars in .env but not in container, vars in container but not in .env.",
+		parameters: Type.Object({
+			container: Type.String({
+				description: "Container or service name to check",
+			}),
+			env_file: Type.Optional(
+				Type.String({
+					description: "Path to .env file on host (default: .env)",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			if (!dockerAvailable()) {
+				return {
+					content: [{ type: "text", text: "Docker is not running or not installed." }],
+					details: {},
+				};
+			}
+
+			const envFile = params.env_file ?? ".env";
+			const cwd = process.cwd();
+			const envPath = join(cwd, envFile);
+
+			if (!existsSync(envPath)) {
+				return {
+					content: [{ type: "text", text: `File not found: ${envFile}` }],
+					details: {},
+				};
+			}
+
+			// Parse host .env
+			const hostEnv = new Map<string, string>();
+			const envContent = readFileSync(envPath, "utf-8");
+			for (const line of envContent.split("\n")) {
+				const trimmed = line.trim();
+				if (!trimmed || trimmed.startsWith("#")) continue;
+				const eqIdx = trimmed.indexOf("=");
+				if (eqIdx === -1) continue;
+				const key = trimmed.slice(0, eqIdx).trim();
+				const value = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, "");
+				hostEnv.set(key, value);
+			}
+
+			// Get container env
+			const containerEnvRaw = exec(`docker exec ${params.container} env`, undefined, 10000);
+			const containerEnv = new Map<string, string>();
+			for (const line of containerEnvRaw.split("\n")) {
+				const eqIdx = line.indexOf("=");
+				if (eqIdx === -1) continue;
+				containerEnv.set(line.slice(0, eqIdx), line.slice(eqIdx + 1));
+			}
+
+			// Compare
+			const missing: string[] = [];
+			const different: string[] = [];
+			const extraInContainer: string[] = [];
+
+			for (const [key, hostValue] of hostEnv) {
+				if (!containerEnv.has(key)) {
+					missing.push(key);
+				} else if (containerEnv.get(key) !== hostValue) {
+					different.push(`${key}: host="${hostValue}" container="${containerEnv.get(key)}"`);
+				}
+			}
+
+			// Skip common system vars for "extra in container" check
+			const systemVars = new Set([
+				"PATH", "HOME", "HOSTNAME", "TERM", "SHLVL", "PWD", "LANG", "LC_ALL",
+				"GPG_KEY", "PHPIZE_DEPS", "PHP_INI_DIR", "PHP_VERSION", "PHP_SHA256",
+				"COMPOSER_ALLOW_SUPERUSER", "NODE_VERSION", "YARN_VERSION",
+			]);
+			for (const [key] of containerEnv) {
+				if (!hostEnv.has(key) && !systemVars.has(key) && !key.startsWith("_")) {
+					extraInContainer.push(key);
+				}
+			}
+
+			const parts = [`# Environment Check: ${envFile} vs ${params.container}\n`];
+
+			if (missing.length === 0 && different.length === 0) {
+				parts.push("All host .env variables are present in the container with matching values.\n");
+			}
+
+			if (missing.length > 0) {
+				parts.push(`## Missing in container (${missing.length})\n`);
+				parts.push("These variables are in your .env but not in the container:\n");
+				for (const key of missing) parts.push(`- \`${key}\``);
+				parts.push("");
+			}
+
+			if (different.length > 0) {
+				parts.push(`## Different values (${different.length})\n`);
+				for (const diff of different) parts.push(`- ${diff}`);
+				parts.push("");
+			}
+
+			if (extraInContainer.length > 0) {
+				parts.push(`## Only in container (${extraInContainer.length})\n`);
+				parts.push("These are set in the container but not in your .env:\n");
+				for (const key of extraInContainer) parts.push(`- \`${key}\``);
+				parts.push("");
+			}
+
+			return {
+				content: [{ type: "text", text: parts.join("\n") }],
+				details: {
+					missing: missing.length,
+					different: different.length,
+					extra: extraInContainer.length,
+				},
+			};
+		},
+	});
+
+	// ── Command: /docker ────────────────────────────────────────────────────
+
+	elyra.registerCommand("docker", {
+		description: "Docker container status dashboard",
+		handler: async (_args, ctx) => {
+			if (!dockerAvailable()) {
+				ctx.ui.notify("Docker is not running or not installed.", "error");
+				return;
+			}
+
+			const ps = exec(
+				'docker ps --format "{{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"',
+			);
+
+			if (!ps) {
+				ctx.ui.notify("No Docker containers running.", "info");
+				return;
+			}
+
+			const lines = ps.split("\n").map((line) => {
+				const [name, image, status, ports] = line.split("\t");
+				return `  ${name}\t${image}\t${status}\t${ports || ""}`;
+			});
+
+			ctx.ui.notify(
+				`Docker Containers:\n\n${lines.join("\n")}`,
+				"info",
+			);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@elyracode/docker",
+  "version": "0.5.12",
+  "description": "Docker-aware development for Elyra -- container exec, log tailing, compose operations, environment sync",
+  "type": "module",
+  "keywords": [
+    "elyra-package",
+    "docker",
+    "containers",
+    "docker-compose",
+    "devops"
+  ],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/docker"
+  },
+  "elyra": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}

package/skills/elyra-docker/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: elyra-docker
+description: Docker container awareness. Use when the project has docker-compose.yml or Dockerfile, or when the user asks about containers, logs, or Docker operations.
+---
+
+# Docker Development
+
+## When to Use
+
+Use Docker tools when:
+- The project has a docker-compose.yml or compose.yml
+- The user asks to run commands that should execute inside a container
+- The user needs container logs or status
+- Environment variable mismatches between host and container need debugging
+
+## Available Tools
+
+| Tool | Use when |
+|------|----------|
+| `docker_exec` | Running commands inside containers (migrations, tests, builds) |
+| `docker_logs` | Reading application or service logs from containers |
+| `docker_status` | Checking what's running, ports, resource usage |
+| `docker_compose` | Starting, stopping, restarting, or rebuilding services |
+| `docker_env_check` | Debugging environment variable mismatches |
+
+## Container Routing
+
+When a project uses Docker, commands like `php artisan migrate`, `npm test`, or `python manage.py` should typically run inside the appropriate container, not on the host. Use `docker_exec` to route these commands.
+
+Common container names to look for:
+- app, web, api -- the main application
+- node, frontend -- JavaScript/Node.js services
+- db, mysql, postgres, redis -- data services
+- nginx, caddy -- web servers
+- worker, queue -- background job processors
+
+## Rules
+
+- Always check `docker_status` first if unsure which containers are running
+- Use `docker_logs` before debugging -- the answer is often in the logs
+- Run `docker_env_check` when environment-related bugs appear
+- Prefer `docker_compose restart <service>` over `docker compose down && up` for faster iteration