@procedures/docker 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,87 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/docker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Docker and Docker Compose as typed procedures: ps, run, exec, logs (streaming), build, pull, stop, rm, compose up and down, run with argv and no shell injection.",
+  "keywords": [
+    "docker",
+    "docker-compose",
+    "containers",
+    "devops",
+    "automation",
+    "procedures"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/client-docker"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
+    },
+    "./register.js": {
+      "import": "./dist/register.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/register.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@procedures/client": "0.2.0",
+    "@procedures/shell": "0.2.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3",
+    "@types/node": "^22.0.0"
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run --exclude '**/*.integration.test.ts'",
+    "test:watch": "vitest",
+    "test:unit": "vitest run --exclude '**/*.integration.test.ts'",
+    "test:integration": "vitest run __tests__/docker.integration.test.ts",
+    "test:coverage": "vitest run --coverage"
+  }
 }

package/src/index.ts

@@ -0,0 +1,75 @@
+/**
+ * @procedures/docker
+ *
+ * Wraps Docker CLI commands as procedures using client-shell.
+ *
+ * @example
+ * ```typescript
+ * import { Client } from "@procedures/client";
+ *
+ * // Run a container
+ * await client.call(["docker", "run"], {
+ *   image: "nginx:latest",
+ *   name: "my-nginx",
+ *   ports: ["8080:80"],
+ *   detach: true,
+ * });
+ *
+ * // Build an image
+ * await client.call(["docker", "build"], {
+ *   context: ".",
+ *   tag: "my-app:latest",
+ * });
+ *
+ * // Docker compose up
+ * await client.call(["docker", "compose", "up"], {
+ *   detach: true,
+ * });
+ * ```
+ */
+
+// Types
+export type {
+  DockerRunInput,
+  DockerBuildInput,
+  DockerPullInput,
+  DockerExecInput,
+  DockerStopInput,
+  DockerRmInput,
+  DockerPsInput,
+  DockerLogsInput,
+  DockerComposeUpInput,
+  DockerComposeDownInput,
+  DockerCommandOutput,
+} from "./types.js";
+export type { DockerLogItem } from "./procedures/docker/logs.js";
+
+export {
+  DockerRunInputSchema,
+  DockerBuildInputSchema,
+  DockerPullInputSchema,
+  DockerExecInputSchema,
+  DockerStopInputSchema,
+  DockerRmInputSchema,
+  DockerPsInputSchema,
+  DockerLogsInputSchema,
+  DockerComposeUpInputSchema,
+  DockerComposeDownInputSchema,
+} from "./types.js";
+
+// Procedures
+export {
+  dockerRun,
+  dockerBuild,
+  dockerPull,
+  dockerExec,
+  dockerStop,
+  dockerRm,
+  dockerPs,
+  dockerLogs,
+  dockerComposeUp,
+  dockerComposeDown,
+} from "./procedures/docker/index.js";
+
+// Registration
+export { registerDockerProcedures } from "./module.js";

package/src/module.ts

@@ -0,0 +1,266 @@
+/**
+ * Module (no side effects): the procedures of this package as data, for `createRegistry()`.
+ *
+ * Procedure Registration for Docker operations
+ *
+ * Provides docker.run, docker.build, docker.pull, docker.exec, docker.stop,
+ * docker.rm, docker.ps, docker.logs, docker.compose.up, docker.compose.down procedures.
+ */
+
+
+import { createProcedure, zodAdapter, defineModule, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
+import shellModule from "@procedures/shell/module";
+import {
+  dockerRun,
+  dockerBuild,
+  dockerPull,
+  dockerExec,
+  dockerStop,
+  dockerRm,
+  dockerPs,
+  dockerLogs,
+  dockerComposeUp,
+  dockerComposeDown,
+} from "./procedures/docker/index.js";
+import type { DockerLogItem } from "./procedures/docker/index.js";
+import {
+  DockerRunInputSchema,
+  DockerBuildInputSchema,
+  DockerPullInputSchema,
+  DockerExecInputSchema,
+  DockerStopInputSchema,
+  DockerRmInputSchema,
+  DockerPsInputSchema,
+  DockerLogsInputSchema,
+  DockerComposeUpInputSchema,
+  DockerComposeDownInputSchema,
+  type DockerRunInput,
+  type DockerBuildInput,
+  type DockerPullInput,
+  type DockerExecInput,
+  type DockerStopInput,
+  type DockerRmInput,
+  type DockerPsInput,
+  type DockerLogsInput,
+  type DockerComposeUpInput,
+  type DockerComposeDownInput,
+  type DockerCommandOutput,
+  DockerCommandOutputSchema,
+  DockerLogsOutputSchema,
+} from "./types.js";
+import type { ProcedureContext } from "@procedures/client";
+
+// =============================================================================
+// Procedures
+// =============================================================================
+
+const dockerRunProcedure = createProcedure()
+  .path(["docker", "run"])
+  .input(zodAdapter<DockerRunInput>(DockerRunInputSchema))
+  .output(zodAdapter<DockerCommandOutput>(DockerCommandOutputSchema))
+  .meta({
+    description: "Run a Docker container",
+    calls: ["shell.run"],
+    // The container runs the image and command of the caller. The volumes give it host files, and
+    // docker pulls a missing image.
+    effects: { reads: ["docker", "fs", "network"], writes: ["docker", "fs", "process"] },
+    args: ["image"],
+    shorts: { name: "n", detach: "d" },
+    output: "json",
+  })
+  .handler(async (input: DockerRunInput, ctx: ProcedureContext): Promise<DockerCommandOutput> => {
+    return dockerRun(input, ctx);
+  })
+  .build();
+
+const dockerBuildProcedure = createProcedure()
+  .path(["docker", "build"])
+  .input(zodAdapter<DockerBuildInput>(DockerBuildInputSchema))
+  .output(zodAdapter<DockerCommandOutput>(DockerCommandOutputSchema))
+  .meta({
+    description: "Build a Docker image",
+    calls: ["shell.run"],
+    // The RUN steps of the Dockerfile are code of the project. Docker reads the context and pulls
+    // the base images. The tag goes to the new image, and the earlier image stays.
+    effects: { reads: ["docker", "fs", "network"], writes: ["docker", "process"], destructive: false },
+    args: ["context"],
+    shorts: { tag: "t", dockerfile: "f" },
+    output: "json",
+  })
+  .handler(async (input: DockerBuildInput, ctx: ProcedureContext): Promise<DockerCommandOutput> => {
+    return dockerBuild(input, ctx);
+  })
+  .build();
+
+const dockerPullProcedure = createProcedure()
+  .path(["docker", "pull"])
+  .input(zodAdapter<DockerPullInput>(DockerPullInputSchema))
+  .output(zodAdapter<DockerCommandOutput>(DockerCommandOutputSchema))
+  .meta({
+    description: "Pull a Docker image",
+    calls: ["shell.run"],
+    effects: { reads: ["docker", "network"], writes: ["docker"], destructive: false, idempotent: true },
+    args: ["image"],
+    output: "json",
+  })
+  .handler(async (input: DockerPullInput, ctx: ProcedureContext): Promise<DockerCommandOutput> => {
+    return dockerPull(input, ctx);
+  })
+  .build();
+
+const dockerExecProcedure = createProcedure()
+  .path(["docker", "exec"])
+  .input(zodAdapter<DockerExecInput>(DockerExecInputSchema))
+  .output(zodAdapter<DockerCommandOutput>(DockerCommandOutputSchema))
+  .meta({
+    description: "Execute command in a running container",
+    calls: ["shell.run"],
+    // The container runs the command of the caller
+    effects: { reads: ["docker"], writes: ["docker", "process"] },
+    args: ["container", "command"],
+    shorts: { interactive: "i", tty: "t", workdir: "w" },
+    output: "json",
+  })
+  .handler(async (input: DockerExecInput, ctx: ProcedureContext): Promise<DockerCommandOutput> => {
+    return dockerExec(input, ctx);
+  })
+  .build();
+
+const dockerStopProcedure = createProcedure()
+  .path(["docker", "stop"])
+  .input(zodAdapter<DockerStopInput>(DockerStopInputSchema))
+  .output(zodAdapter<DockerCommandOutput>(DockerCommandOutputSchema))
+  .meta({
+    description: "Stop running container(s)",
+    calls: ["shell.run"],
+    // The stop of a stopped container changes nothing
+    effects: { reads: ["docker"], writes: ["docker"], idempotent: true },
+    args: ["containers"],
+    shorts: { time: "t" },
+    output: "json",
+  })
+  .handler(async (input: DockerStopInput, ctx: ProcedureContext): Promise<DockerCommandOutput> => {
+    return dockerStop(input, ctx);
+  })
+  .build();
+
+const dockerRmProcedure = createProcedure()
+  .path(["docker", "rm"])
+  .input(zodAdapter<DockerRmInput>(DockerRmInputSchema))
+  .output(zodAdapter<DockerCommandOutput>(DockerCommandOutputSchema))
+  .meta({
+    description: "Remove container(s)",
+    calls: ["shell.run"],
+    effects: { reads: ["docker"], writes: ["docker"] },
+    args: ["containers"],
+    shorts: { force: "f", volumes: "v" },
+    output: "json",
+  })
+  .handler(async (input: DockerRmInput, ctx: ProcedureContext): Promise<DockerCommandOutput> => {
+    return dockerRm(input, ctx);
+  })
+  .build();
+
+const dockerPsProcedure = createProcedure()
+  .path(["docker", "ps"])
+  .input(zodAdapter<DockerPsInput>(DockerPsInputSchema))
+  .output(zodAdapter<DockerCommandOutput>(DockerCommandOutputSchema))
+  .meta({
+    description: "List containers",
+    calls: ["shell.run"],
+    effects: { reads: ["docker"], writes: [] },
+    shorts: { all: "a", filter: "f", format: "F" },
+    output: "json",
+  })
+  .handler(async (input: DockerPsInput, ctx: ProcedureContext): Promise<DockerCommandOutput> => {
+    return dockerPs(input, ctx);
+  })
+  .build();
+
+const dockerLogsProcedure = createProcedure()
+  .path(["docker", "logs"])
+  .input(zodAdapter<DockerLogsInput>(DockerLogsInputSchema))
+  // One value, or with follow one item for each log line (a stream)
+  .output(zodAdapter<DockerCommandOutput | DockerLogItem>(DockerLogsOutputSchema))
+  .meta({
+    description: "Get container logs",
+    calls: ["shell.run", "shell.stream"],
+    effects: { reads: ["docker"], writes: [] },
+    args: ["container"],
+    shorts: { follow: "f", tail: "n", timestamps: "t" },
+    output: "json",
+  })
+  // With follow, the promise gives a stream: invokeProcedure reads a returned async iterable as a
+  // stream, and the handler types of the core do not describe that case
+  .handler((input: DockerLogsInput, ctx: ProcedureContext) =>
+    dockerLogs(input, ctx) as unknown as Promise<DockerCommandOutput | DockerLogItem>
+  )
+  .build();
+
+const dockerComposeUpProcedure = createProcedure()
+  .path(["docker", "compose", "up"])
+  .input(zodAdapter<DockerComposeUpInput>(DockerComposeUpInputSchema))
+  .output(zodAdapter<DockerCommandOutput>(DockerCommandOutputSchema))
+  .meta({
+    description: "Start services with docker compose",
+    calls: ["shell.run"],
+    // The compose file of the caller sets the images, the commands and the host folders of the
+    // services. An up can replace the containers of changed services.
+    effects: { reads: ["docker", "fs", "network"], writes: ["docker", "fs", "process"] },
+    shorts: { file: "f", detach: "d", build: "b" },
+    output: "json",
+  })
+  .handler(async (input: DockerComposeUpInput, ctx: ProcedureContext): Promise<DockerCommandOutput> => {
+    return dockerComposeUp(input, ctx);
+  })
+  .build();
+
+const dockerComposeDownProcedure = createProcedure()
+  .path(["docker", "compose", "down"])
+  .input(zodAdapter<DockerComposeDownInput>(DockerComposeDownInputSchema))
+  .output(zodAdapter<DockerCommandOutput>(DockerCommandOutputSchema))
+  .meta({
+    description: "Stop services with docker compose",
+    calls: ["shell.run"],
+    // It removes the containers of the project, and with volumes: true its volumes. A second down
+    // changes nothing.
+    effects: { reads: ["docker", "fs"], writes: ["docker"], idempotent: true },
+    shorts: { file: "f", volumes: "v" },
+    output: "json",
+  })
+  .handler(async (input: DockerComposeDownInput, ctx: ProcedureContext): Promise<DockerCommandOutput> => {
+    return dockerComposeDown(input, ctx);
+  })
+  .build();
+
+// =============================================================================
+// Registration
+// =============================================================================
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const dockerModule: ProcedureModule = defineModule("@procedures/docker", [
+    dockerRunProcedure,
+    dockerBuildProcedure,
+    dockerPullProcedure,
+    dockerExecProcedure,
+    dockerStopProcedure,
+    dockerRmProcedure,
+    dockerPsProcedure,
+    dockerLogsProcedure,
+    dockerComposeUpProcedure,
+    dockerComposeDownProcedure,
+  ], [shellModule]);
+
+export default dockerModule;
+
+/**
+ * This function registers the procedures of @procedures/docker, and of the modules that it requires, in
+ * a registry. The default is the global registry. Importing this file registers nothing: the
+ * `./register` entry starts this function (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+export function registerDockerProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [dockerModule]);
+}

package/src/procedures/docker/build.ts

@@ -0,0 +1,46 @@
+/**
+ * docker.build procedure
+ *
+ * Build a Docker image.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { dockerArg, runDocker } from "./shared.js";
+import type { DockerBuildInput, DockerCommandOutput } from "../../types.js";
+
+/**
+ * Build a Docker image
+ */
+export async function dockerBuild(
+  input: DockerBuildInput,
+  ctx: ProcedureContext
+): Promise<DockerCommandOutput> {
+  {
+    const args: string[] = ["build"];
+
+    // Add tag
+    args.push("-t", input.tag);
+
+    // Add dockerfile if specified
+    if (input.dockerfile) {
+      args.push("-f", input.dockerfile);
+    }
+
+    // Add build args
+    if (input.buildArgs) {
+      for (const [key, value] of Object.entries(input.buildArgs)) {
+        args.push("--build-arg", `${key}=${value}`);
+      }
+    }
+
+    // Add no-cache flag
+    if (input.noCache) {
+      args.push("--no-cache");
+    }
+
+    // Add context
+    args.push(dockerArg("context", input.context));
+
+    return runDocker(args, input, ctx);
+  }
+}

package/src/procedures/docker/down.ts

@@ -0,0 +1,31 @@
+/**
+ * docker.compose.down procedure
+ *
+ * Stop services with docker compose.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { runDocker } from "./shared.js";
+import type { DockerComposeDownInput, DockerCommandOutput } from "../../types.js";
+
+/**
+ * Stop services with docker compose
+ */
+export async function dockerComposeDown(
+  input: DockerComposeDownInput,
+  ctx: ProcedureContext
+): Promise<DockerCommandOutput> {
+  {
+    const args: string[] = ["compose"];
+
+    if (input.file) args.push("-f", input.file);
+
+    args.push("down");
+
+    if (input.volumes) args.push("-v");
+    if (input.removeOrphans) args.push("--remove-orphans");
+    if (input.rmi) args.push("--rmi", input.rmi);
+
+    return runDocker(args, input, ctx);
+  }
+}

package/src/procedures/docker/exec.ts

@@ -0,0 +1,37 @@
+/**
+ * docker.exec procedure
+ *
+ * Execute command in a running container.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { dockerArg, runDocker, words } from "./shared.js";
+import type { DockerExecInput, DockerCommandOutput } from "../../types.js";
+
+/**
+ * Execute command in container
+ */
+export async function dockerExec(
+  input: DockerExecInput,
+  ctx: ProcedureContext
+): Promise<DockerCommandOutput> {
+  {
+    const args: string[] = ["exec"];
+
+    if (input.interactive) args.push("-i");
+    if (input.tty) args.push("-t");
+    if (input.workdir) args.push("-w", input.workdir);
+
+    // Add environment variables
+    if (input.env) {
+      for (const [key, value] of Object.entries(input.env)) {
+        args.push("-e", `${key}=${value}`);
+      }
+    }
+
+    args.push(dockerArg("container", input.container));
+    args.push(...words(input.command));
+
+    return runDocker(args, input, ctx);
+  }
+}

package/src/procedures/docker/index.ts

@@ -0,0 +1,10 @@
+export { dockerRun } from "./run.js";
+export { dockerBuild } from "./build.js";
+export { dockerPull } from "./pull.js";
+export { dockerExec } from "./exec.js";
+export { dockerStop } from "./stop.js";
+export { dockerRm } from "./rm.js";
+export { dockerPs } from "./ps.js";
+export { dockerLogs, type DockerLogItem } from "./logs.js";
+export { dockerComposeUp } from "./up.js";
+export { dockerComposeDown } from "./down.js";

package/src/procedures/docker/logs.ts

@@ -0,0 +1,52 @@
+/**
+ * docker.logs procedure
+ *
+ * Get container logs. With `follow`, the procedure is a stream: each log line is an item while
+ * the container runs. The stream ends when the reader stops or the signal aborts, and that ends
+ * `docker logs -f`. Before, `follow` waited for docker to end, so the call gave nothing until a
+ * timeout or a cancel.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { dockerArg, runDocker } from "./shared.js";
+import type { DockerLogsInput, DockerCommandOutput, DockerLogItem } from "../../types.js";
+
+// The type lives in types.ts, next to its output schema
+export type { DockerLogItem };
+
+/**
+ * Get container logs: one value, or with `follow` a stream of lines
+ */
+export async function dockerLogs(
+  input: DockerLogsInput,
+  ctx: ProcedureContext
+): Promise<DockerCommandOutput | AsyncGenerator<DockerLogItem, void, undefined>> {
+  const args: string[] = ["logs"];
+
+  if (input.follow) args.push("-f");
+  if (input.tail !== undefined) args.push("--tail", String(input.tail));
+  if (input.timestamps) args.push("-t");
+
+  // The guard runs before anything starts, also for a stream
+  args.push(dockerArg("container", input.container));
+
+  if (input.follow) {
+    return followLogs(args, input, ctx);
+  }
+  return runDocker(args, input, ctx);
+}
+
+/** The lines of `docker <args>` through shell.stream, which runs no shell and ends the program when the reader stops. */
+async function* followLogs(
+  args: string[],
+  input: DockerLogsInput,
+  ctx: ProcedureContext
+): AsyncGenerator<DockerLogItem, void, undefined> {
+  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;
+  if (!ctx.client.stream) {
+    throw new Error("docker.logs with follow needs a host whose client can stream");
+  }
+  yield* ctx.client.stream<typeof shellInput, DockerLogItem>(["shell", "stream"], shellInput);
+}

package/src/procedures/docker/ps.ts

@@ -0,0 +1,27 @@
+/**
+ * docker.ps procedure
+ *
+ * List containers.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { runDocker } from "./shared.js";
+import type { DockerPsInput, DockerCommandOutput } from "../../types.js";
+
+/**
+ * List containers
+ */
+export async function dockerPs(
+  input: DockerPsInput,
+  ctx: ProcedureContext
+): Promise<DockerCommandOutput> {
+  {
+    const args: string[] = ["ps"];
+
+    if (input.all) args.push("-a");
+    if (input.filter) args.push("--filter", input.filter);
+    if (input.format) args.push("--format", input.format);
+
+    return runDocker(args, input, ctx);
+  }
+}

package/src/procedures/docker/pull.ts

@@ -0,0 +1,23 @@
+/**
+ * docker.pull procedure
+ *
+ * Pull a Docker image.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { dockerArg, runDocker } from "./shared.js";
+import type { DockerPullInput, DockerCommandOutput } from "../../types.js";
+
+/**
+ * Pull a Docker image
+ */
+export async function dockerPull(
+  input: DockerPullInput,
+  ctx: ProcedureContext
+): Promise<DockerCommandOutput> {
+  {
+    const imageWithTag = input.tag ? `${input.image}:${input.tag}` : input.image;
+    const args = ["pull", dockerArg("image", imageWithTag)];
+    return runDocker(args, input, ctx);
+  }
+}

package/src/procedures/docker/rm.ts

@@ -0,0 +1,28 @@
+/**
+ * docker.rm procedure
+ *
+ * Remove container(s).
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { dockerArg, runDocker } from "./shared.js";
+import type { DockerRmInput, DockerCommandOutput } from "../../types.js";
+
+/**
+ * Remove container(s)
+ */
+export async function dockerRm(
+  input: DockerRmInput,
+  ctx: ProcedureContext
+): Promise<DockerCommandOutput> {
+  {
+    const args: string[] = ["rm"];
+
+    if (input.force) args.push("-f");
+    if (input.volumes) args.push("-v");
+
+    args.push(...input.containers.map((c) => dockerArg("container", c)));
+
+    return runDocker(args, input, ctx);
+  }
+}