@procedures/docker 0.0.0-stage → 0.1.0

package/src/procedures/docker/run.ts

@@ -0,0 +1,65 @@
+/**
+ * docker.run procedure
+ *
+ * Run a Docker container.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { dockerArg, runDocker, words } from "./shared.js";
+import type { DockerRunInput, DockerCommandOutput } from "../../types.js";
+
+/**
+ * Run a Docker container
+ *
+ * @example
+ * // Run nginx in detached mode
+ * await client.call(["docker", "run"], {
+ *   image: "nginx:latest",
+ *   name: "my-nginx",
+ *   ports: ["8080:80"],
+ *   detach: true,
+ * });
+ */
+export async function dockerRun(
+  input: DockerRunInput,
+  ctx: ProcedureContext
+): Promise<DockerCommandOutput> {
+  {
+    const args: string[] = ["run"];
+
+    // Add flags
+    if (input.detach) args.push("-d");
+    if (input.rm) args.push("--rm");
+    if (input.name) args.push("--name", input.name);
+
+    // Add port mappings
+    if (input.ports) {
+      for (const port of input.ports) {
+        args.push("-p", port);
+      }
+    }
+
+    // Add volume mappings
+    if (input.volumes) {
+      for (const volume of input.volumes) {
+        args.push("-v", volume);
+      }
+    }
+
+    // Add environment variables
+    if (input.env) {
+      for (const [key, value] of Object.entries(input.env)) {
+        args.push("-e", `${key}=${value}`);
+      }
+    }
+
+    // Add image
+    args.push(dockerArg("image", input.image));
+
+    // Add command if specified
+    if (input.command) {
+      args.push(...words(input.command));
+    }
+    return runDocker(args, input, ctx);
+  }
+}

package/src/procedures/docker/shared.ts

@@ -0,0 +1,62 @@
+/**
+ * The way every docker procedure runs docker: an argument list through `shell.run`, no shell.
+ *
+ * Before, each procedure joined its arguments into one string for `shell.exec`, which runs a
+ * shell, so a value such as `x & calc` ran a second command. `docker.*` is an MCP tool, and
+ * the deep dive ran an injected command through `docker.ps` and through `client.chain`
+ * (documentation/deep-dive-2026-10/wrappers.md, WRP-1).
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { DockerCommandOutput } from "../../types.js";
+
+/**
+ * A value that docker reads as an argument (an image, a container, a path, a service). It must
+ * not start with "-", or docker reads it as an option (for example `--privileged`).
+ */
+export function dockerArg(name: string, value: string): string {
+  if (value.startsWith("-")) {
+    throw new Error(`Invalid ${name} (starts with "-"): ${value}`);
+  }
+  return value;
+}
+
+/** The words of a command string, split at whitespace. No shell runs it, so there is no quoting. */
+export function words(command: string): string[] {
+  return command.trim().split(/\s+/).filter((word) => word.length > 0);
+}
+
+/** This function runs `docker <args>` and gives its result. It does not throw. */
+export async function runDocker(
+  args: string[],
+  input: { cwd?: string | undefined; timeout?: number | undefined },
+  ctx: ProcedureContext
+): Promise<DockerCommandOutput> {
+  const startTime = Date.now();
+  try {
+    const shellInput: { command: string; args: string[]; cwd?: string; timeout?: number } = { command: "docker", args };
+    if (input.cwd !== undefined) shellInput.cwd = input.cwd;
+    if (input.timeout !== undefined) shellInput.timeout = input.timeout;
+
+    const result = await ctx.client.call<
+      typeof shellInput,
+      { exitCode: number; stdout: string; stderr: string }
+    >(["shell", "run"], shellInput);
+
+    return {
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      success: result.exitCode === 0,
+      duration: Date.now() - startTime,
+    };
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: error instanceof Error ? error.message : String(error),
+      success: false,
+      duration: Date.now() - startTime,
+    };
+  }
+}

package/src/procedures/docker/stop.ts

@@ -0,0 +1,29 @@
+/**
+ * docker.stop procedure
+ *
+ * Stop running container(s).
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { dockerArg, runDocker } from "./shared.js";
+import type { DockerStopInput, DockerCommandOutput } from "../../types.js";
+
+/**
+ * Stop container(s)
+ */
+export async function dockerStop(
+  input: DockerStopInput,
+  ctx: ProcedureContext
+): Promise<DockerCommandOutput> {
+  {
+    const args: string[] = ["stop"];
+
+    if (input.time !== undefined) {
+      args.push("-t", String(input.time));
+    }
+
+    args.push(...input.containers.map((c) => dockerArg("container", c)));
+
+    return runDocker(args, input, ctx);
+  }
+}

package/src/procedures/docker/up.ts

@@ -0,0 +1,35 @@
+/**
+ * docker.compose.up procedure
+ *
+ * Start services with docker compose.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { dockerArg, runDocker } from "./shared.js";
+import type { DockerComposeUpInput, DockerCommandOutput } from "../../types.js";
+
+/**
+ * Start services with docker compose
+ */
+export async function dockerComposeUp(
+  input: DockerComposeUpInput,
+  ctx: ProcedureContext
+): Promise<DockerCommandOutput> {
+  {
+    const args: string[] = ["compose"];
+
+    if (input.file) args.push("-f", input.file);
+
+    args.push("up");
+
+    if (input.detach) args.push("-d");
+    if (input.build) args.push("--build");
+    if (input.forceRecreate) args.push("--force-recreate");
+
+    if (input.services && input.services.length > 0) {
+      args.push(...input.services.map((s) => dockerArg("service", s)));
+    }
+
+    return runDocker(args, input, ctx);
+  }
+}

package/src/register.ts

@@ -0,0 +1,20 @@
+/**
+ * Importing this file registers the procedures of @procedures/docker in the global registry
+ * (DECISIONS-2026-10, "Every package root registers its procedures"). The procedures as data
+ * are in `module.ts`, which registers nothing: a host with its own registry uses that one.
+ */
+
+// Import shell dependency to ensure shell.exec is registered
+import "@procedures/shell";
+
+import { registerProcedures } from "@procedures/client";
+import { dockerModule } from "./module.js";
+
+export * from "./module.js";
+
+export function registerDockerProcedures(): void {
+  registerProcedures(dockerModule.procedures);
+}
+
+// Auto-register when this module is loaded
+registerDockerProcedures();

package/src/types.ts

@@ -0,0 +1,351 @@
+/**
+ * Type definitions for client-docker procedures
+ *
+ * client-docker wraps Docker CLI commands as procedures using client-shell.
+ */
+
+import { z } from "zod";
+
+// =============================================================================
+// Shared Output Type
+// =============================================================================
+
+export interface DockerCommandOutput {
+  /** Exit code of the command */
+  exitCode: number;
+  /** Standard output */
+  stdout: string;
+  /** Standard error */
+  stderr: string;
+  /** Whether command succeeded (exit code 0) */
+  success: boolean;
+  /** Duration in milliseconds */
+  duration: number;
+}
+
+/** One item of a followed log: a line of the container, or the end of `docker logs` (the last item). */
+export type DockerLogItem =
+  | { type: "stdout" | "stderr"; line: string }
+  | {
+      type: "exit";
+      exitCode: number;
+      duration: number;
+      signal?: string | undefined;
+      timedOut?: boolean | undefined;
+      aborted?: boolean | undefined;
+    };
+
+// Output schemas (roadmap 2.1). Loose objects: a field that a schema does not name stays in the
+// result (a strict schema would remove it when the output is validated).
+
+/** The result of a docker command: every docker.* procedure gives it. */
+export const DockerCommandOutputSchema: z.ZodType<DockerCommandOutput> = z.looseObject({
+  exitCode: z.number().describe("The exit code of docker (0 is success)"),
+  stdout: z.string().describe("The standard output of docker"),
+  stderr: z.string().describe("The standard error of docker, or the error message when docker did not start"),
+  success: z.boolean().describe("True when the exit code is 0"),
+  duration: z.number().describe("The time of the command, in milliseconds"),
+});
+
+/** docker.logs: one result, or with follow a stream of lines and one last exit item. */
+export const DockerLogsOutputSchema: z.ZodType<DockerCommandOutput | DockerLogItem> = z.union([
+  DockerCommandOutputSchema,
+  z.looseObject({
+    type: z.enum(["stdout", "stderr"]).describe("The stream of the line"),
+    line: z.string().describe("One line of the log, without its line end"),
+  }),
+  z.looseObject({
+    type: z.literal("exit").describe("The end of the stream"),
+    exitCode: z.number().describe("The exit code of docker logs"),
+    duration: z.number().describe("The time of the stream, in milliseconds"),
+    signal: z.string().optional().describe("The signal that ended docker logs"),
+    timedOut: z.boolean().optional().describe("True when the timeout ended the stream"),
+    aborted: z.boolean().optional().describe("True when the reader or the signal ended the stream"),
+  }),
+]);
+
+// =============================================================================
+// docker.run Types
+// =============================================================================
+
+export const DockerRunInputSchema: z.ZodObject<{
+  image: z.ZodString;
+  name: z.ZodOptional<z.ZodString>;
+  ports: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  volumes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  detach: z.ZodOptional<z.ZodBoolean>;
+  rm: z.ZodOptional<z.ZodBoolean>;
+  command: z.ZodOptional<z.ZodString>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Docker image to run */
+  image: z.string().describe("Docker image to run"),
+  /** Container name */
+  name: z.string().optional().describe("Container name"),
+  /** Port mappings (e.g., ["8080:80", "3000:3000"]) */
+  ports: z.array(z.string()).optional().describe("Port mappings (e.g., [\"8080:80\", \"3000:3000\"])"),
+  /** Volume mappings (e.g., ["/host:/container"]) */
+  volumes: z.array(z.string()).optional().describe("Volume mappings (e.g., [\"/host:/container\"])"),
+  /** Environment variables */
+  env: z.record(z.string(), z.string()).optional().describe("Environment variables"),
+  /** Run in detached mode */
+  detach: z.boolean().optional().describe("Run in detached mode"),
+  /** Automatically remove container when it exits */
+  rm: z.boolean().optional().describe("Automatically remove container when it exits"),
+  /** Command to run in container */
+  command: z.string().optional().describe("Command to run in container"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type DockerRunInput = z.infer<typeof DockerRunInputSchema>;
+
+// =============================================================================
+// docker.build Types
+// =============================================================================
+
+export const DockerBuildInputSchema: z.ZodObject<{
+  context: z.ZodString;
+  tag: z.ZodString;
+  dockerfile: z.ZodOptional<z.ZodString>;
+  buildArgs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  noCache: z.ZodOptional<z.ZodBoolean>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Build context path */
+  context: z.string().describe("Build context path"),
+  /** Image tag */
+  tag: z.string().describe("Image tag"),
+  /** Dockerfile path (relative to context) */
+  dockerfile: z.string().optional().describe("Dockerfile path (relative to context)"),
+  /** Build arguments */
+  buildArgs: z.record(z.string(), z.string()).optional().describe("Build arguments"),
+  /** Do not use cache when building */
+  noCache: z.boolean().optional().describe("Do not use cache when building"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type DockerBuildInput = z.infer<typeof DockerBuildInputSchema>;
+
+// =============================================================================
+// docker.pull Types
+// =============================================================================
+
+export const DockerPullInputSchema: z.ZodObject<{
+  image: z.ZodString;
+  tag: z.ZodOptional<z.ZodString>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Image to pull */
+  image: z.string().describe("Image to pull"),
+  /** Image tag (default: latest) */
+  tag: z.string().optional().describe("Image tag (default: latest)"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type DockerPullInput = z.infer<typeof DockerPullInputSchema>;
+
+// =============================================================================
+// docker.exec Types
+// =============================================================================
+
+export const DockerExecInputSchema: z.ZodObject<{
+  container: z.ZodString;
+  command: z.ZodString;
+  interactive: z.ZodOptional<z.ZodBoolean>;
+  tty: z.ZodOptional<z.ZodBoolean>;
+  workdir: z.ZodOptional<z.ZodString>;
+  env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Container name or ID */
+  container: z.string().describe("Container name or ID"),
+  /** Command to execute */
+  command: z.string().describe("Command to execute"),
+  /** Run interactively */
+  interactive: z.boolean().optional().describe("Run interactively"),
+  /** Allocate a TTY */
+  tty: z.boolean().optional().describe("Allocate a TTY"),
+  /** Working directory inside container */
+  workdir: z.string().optional().describe("Working directory inside container"),
+  /** Environment variables */
+  env: z.record(z.string(), z.string()).optional().describe("Environment variables"),
+  /** Working directory (host) */
+  cwd: z.string().optional().describe("Working directory (host)"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type DockerExecInput = z.infer<typeof DockerExecInputSchema>;
+
+// =============================================================================
+// docker.stop Types
+// =============================================================================
+
+export const DockerStopInputSchema: z.ZodObject<{
+  containers: z.ZodArray<z.ZodString>;
+  time: z.ZodOptional<z.ZodNumber>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Container name(s) or ID(s) */
+  containers: z.array(z.string()).describe("Container name(s) or ID(s)"),
+  /** Seconds to wait before killing */
+  time: z.number().optional().describe("Seconds to wait before killing"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type DockerStopInput = z.infer<typeof DockerStopInputSchema>;
+
+// =============================================================================
+// docker.rm Types
+// =============================================================================
+
+export const DockerRmInputSchema: z.ZodObject<{
+  containers: z.ZodArray<z.ZodString>;
+  force: z.ZodOptional<z.ZodBoolean>;
+  volumes: z.ZodOptional<z.ZodBoolean>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Container name(s) or ID(s) */
+  containers: z.array(z.string()).describe("Container name(s) or ID(s)"),
+  /** Force removal */
+  force: z.boolean().optional().describe("Force removal"),
+  /** Remove volumes */
+  volumes: z.boolean().optional().describe("Remove volumes"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type DockerRmInput = z.infer<typeof DockerRmInputSchema>;
+
+// =============================================================================
+// docker.ps Types
+// =============================================================================
+
+export const DockerPsInputSchema: z.ZodObject<{
+  all: z.ZodOptional<z.ZodBoolean>;
+  filter: z.ZodOptional<z.ZodString>;
+  format: z.ZodOptional<z.ZodString>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Show all containers (default shows just running) */
+  all: z.boolean().optional().describe("Show all containers (default shows just running)"),
+  /** Filter containers */
+  filter: z.string().optional().describe("Filter containers"),
+  /** Format output */
+  format: z.string().optional().describe("Format output"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type DockerPsInput = z.infer<typeof DockerPsInputSchema>;
+
+// =============================================================================
+// docker.logs Types
+// =============================================================================
+
+export const DockerLogsInputSchema: z.ZodObject<{
+  container: z.ZodString;
+  follow: z.ZodOptional<z.ZodBoolean>;
+  tail: z.ZodOptional<z.ZodNumber>;
+  timestamps: z.ZodOptional<z.ZodBoolean>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Container name or ID */
+  container: z.string().describe("Container name or ID"),
+  /** Follow log output */
+  follow: z.boolean().optional().describe("Follow log output"),
+  /** Number of lines from end */
+  tail: z.number().optional().describe("Number of lines from end"),
+  /** Show timestamps */
+  timestamps: z.boolean().optional().describe("Show timestamps"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type DockerLogsInput = z.infer<typeof DockerLogsInputSchema>;
+
+// =============================================================================
+// docker.compose.up Types
+// =============================================================================
+
+export const DockerComposeUpInputSchema: z.ZodObject<{
+  file: z.ZodOptional<z.ZodString>;
+  services: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  detach: z.ZodOptional<z.ZodBoolean>;
+  build: z.ZodOptional<z.ZodBoolean>;
+  forceRecreate: z.ZodOptional<z.ZodBoolean>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Compose file path */
+  file: z.string().optional().describe("Compose file path"),
+  /** Services to start (default: all) */
+  services: z.array(z.string()).optional().describe("Services to start (default: all)"),
+  /** Detached mode */
+  detach: z.boolean().optional().describe("Detached mode"),
+  /** Build images before starting */
+  build: z.boolean().optional().describe("Build images before starting"),
+  /** Force recreate containers */
+  forceRecreate: z.boolean().optional().describe("Force recreate containers"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type DockerComposeUpInput = z.infer<typeof DockerComposeUpInputSchema>;
+
+// =============================================================================
+// docker.compose.down Types
+// =============================================================================
+
+export const DockerComposeDownInputSchema: z.ZodObject<{
+  file: z.ZodOptional<z.ZodString>;
+  volumes: z.ZodOptional<z.ZodBoolean>;
+  removeOrphans: z.ZodOptional<z.ZodBoolean>;
+  rmi: z.ZodOptional<z.ZodEnum<{ all: "all"; local: "local" }>>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Compose file path */
+  file: z.string().optional().describe("Compose file path"),
+  /** Remove volumes */
+  volumes: z.boolean().optional().describe("Remove volumes"),
+  /** Remove orphan containers */
+  removeOrphans: z.boolean().optional().describe("Remove orphan containers"),
+  /** Remove images (all, local) */
+  rmi: z.enum(["all", "local"]).optional().describe("Remove images (all, local)"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type DockerComposeDownInput = z.infer<typeof DockerComposeDownInputSchema>;