@figulus/schema 0.4.0-alpha-dev → 0.5.0-alpha-dev-2

package/src/core/entities/figstack.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { portMappingSchema } from '../generic.js';
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+
+extendZodWithOpenApi(z);
+
+// ---------------------------------------------------------------------------
+// FigStackDependency
+// ---------------------------------------------------------------------------
+
+export const figStackDependencySchema = z.object({
+  name: z.string().min(1).describe("References another entry's name in this stack."),
+  condition: z.enum(['started', 'healthy', 'completed']).default('started').optional().describe("started — wait for the container to be running; healthy — wait for the health check to pass; completed — wait for the container to exit successfully."),
+}).openapi("FigStackDependency");
+export type FigStackDependency = z.infer<typeof figStackDependencySchema>;
+
+// ---------------------------------------------------------------------------
+// FigStackHealthCheck (discriminated union flattened into one object)
+// ---------------------------------------------------------------------------
+
+export const figStackHealthCheckSchema = z.object({
+  type: z.enum(['exec', 'http', 'tcp']),
+  // exec
+  cmd: z.string().optional().describe("Shell command to run inside the container (exec type only)."),
+  // http
+  path: z.string().optional().describe("HTTP path to check (http type only). Example: /health"),
+  port: z.int().optional().describe("Container port to check (http and tcp types)."),
+  method: z.enum(['GET', 'HEAD']).optional().describe("HTTP method (http type only)."),
+  expectedStatus: z.int().optional().describe("Expected HTTP status code (http type only)."),
+  // shared timing
+  intervalSeconds: z.int().optional(),
+  timeoutSeconds: z.int().optional(),
+  retries: z.int().optional(),
+  startPeriodSeconds: z.int().optional().describe("Grace period before failures count against the retry limit."),
+}).openapi("FigStackHealthCheck");
+export type FigStackHealthCheck = z.infer<typeof figStackHealthCheckSchema>;
+
+// ---------------------------------------------------------------------------
+// FigStackEntry
+// ---------------------------------------------------------------------------
+
+// Inline FigSpec reference: either an object or a string reference
+export const figStackSpecSchema = z.union([
+  z.object({}).passthrough().openapi({ type: "object" }),
+  z.string()
+]).openapi("FigStackSpec");
+
+export const figStackEntrySchema = z.object({
+  name: z.string().min(1).describe("Unique container name within the stack; also the hostname on the shared network.").openapi({ example: "postgres" }),
+  spec: figStackSpecSchema.describe("Inline FigSpec object or string reference (e.g. \"postgres#default\")."),
+  ports: z.array(portMappingSchema).optional().describe("Overrides spec.run.ports for this deployment."),
+  dependsOn: z.array(figStackDependencySchema).optional(),
+  healthCheck: figStackHealthCheckSchema.optional(),
+  env: z.record(z.string(), z.string()).optional().describe("Entry-level environment variable overrides (run-time only)."),
+}).openapi("FigStackEntry");
+export type FigStackEntry = z.infer<typeof figStackEntrySchema>;
+
+// ---------------------------------------------------------------------------
+// FigStackNetworkConfig
+// ---------------------------------------------------------------------------
+
+export const figStackNetworkConfigSchema = z.object({
+  name: z.string().optional().describe("Custom Docker network name. Defaults to {stackName}_network."),
+  subnet: z.string().optional().describe("Optional CIDR for predictable container IPs. Example: 172.20.0.0/16"),
+  external: z.string().optional().describe("Join an existing external Docker network by name instead of creating one."),
+}).openapi("FigStackNetworkConfig");
+export type FigStackNetworkConfig = z.infer<typeof figStackNetworkConfigSchema>;
+
+// ---------------------------------------------------------------------------
+// FigStackVolumeDeclaration
+// ---------------------------------------------------------------------------
+
+export const figStackVolumeDeclarationSchema = z.object({
+  name: z.string().min(1).describe("Exact Docker volume name — no stack prefix is applied."),
+  external: z.boolean().optional().describe("If true, the volume must already exist; the engine will not create it."),
+}).openapi("FigStackVolumeDeclaration");
+export type FigStackVolumeDeclaration = z.infer<typeof figStackVolumeDeclarationSchema>;
+
+// ---------------------------------------------------------------------------
+// FigStackEnvGroup
+// ---------------------------------------------------------------------------
+
+export const figStackEnvGroupSchema = z.object({
+  vars: z.record(z.string(), z.string()),
+  inject: z.array(z.string()).optional().describe("Container names to inject into. Omit to inject into all containers."),
+}).openapi("FigStackEnvGroup");
+export type FigStackEnvGroup = z.infer<typeof figStackEnvGroupSchema>;
+
+// ---------------------------------------------------------------------------
+// FigStack (top-level)
+// ---------------------------------------------------------------------------
+
+export const figStackSchema = z.object({
+  schemaVersion: z.string().openapi({ example: "0.1" }),
+  stackName: z.string().min(1).openapi({ example: "blog" }),
+  containers: z.array(figStackEntrySchema).min(1),
+  env: z.array(figStackEnvGroupSchema).optional(),
+  network: figStackNetworkConfigSchema.optional(),
+  volumes: z.array(figStackVolumeDeclarationSchema).optional(),
+}).openapi("FigStack");
+export type FigStack = z.infer<typeof figStackSchema>;

package/src/core/entities/index.ts

@@ -0,0 +1,2 @@
+export * from './figspec.js';
+export * from './figstack.js';

package/src/core/execute.ts

@@ -0,0 +1,66 @@
+import z from "zod";
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+
+extendZodWithOpenApi(z);
+
+export const mainCmdOnExitWithCodeSchema = z.object({
+  cmd: z.union([z.string(), z.null()]).optional().describe("Action: a command string, \"persist\", \"shutdown\", or null"),
+  exitCode: z.int(),
+}).openapi("MainCmdOnExitWithCode");
+export type MainCmdOnExitWithCode = z.infer<typeof mainCmdOnExitWithCodeSchema>;
+
+export const mainCmdOnExitListSchema = z.array(
+  mainCmdOnExitWithCodeSchema
+);
+
+// onExit accepts: null | "persist" | "shutdown" | command-string | dispatch-table
+export const onExitBehaviorSchema = z.union([
+  z.string(),
+  z.null(),
+  z.array(mainCmdOnExitWithCodeSchema),
+]).openapi("OnExitBehavior");
+export type OnExitBehavior = z.infer<typeof onExitBehaviorSchema>;
+
+export const executeStartupCmdSchema = z.object({
+  cmd: z.string().describe("Shell command to run before the main process"),
+  async: z.boolean().optional().describe("Fire-and-forget if true; blocks main start if false"),
+}).openapi("ExecuteStartupCmd");
+export type ExecuteStartupCmd = z.infer<typeof executeStartupCmdSchema>;
+
+export const executeMainCmdSchema = z.object({
+  cmd: z.string().describe("Primary command the container runs"),
+  onExit: onExitBehaviorSchema.optional(),
+  parser: z.string().optional().describe("JavaScript parser source or URI for structured output"),
+}).openapi("ExecuteMainCmd");
+export type ExecuteMainCmd = z.infer<typeof executeMainCmdSchema>;
+
+export const executeShutdownCmdSchema = z.object({
+  cmd: z.string().describe("Shell command to run before the container stops"),
+}).openapi("ExecuteShutdownCmd");
+export type ExecuteShutdownCmd = z.infer<typeof executeShutdownCmdSchema>;
+
+export const scheduleExpressionStructSchema = z.object({
+  interval: z.int().optional().describe("Seconds after startup, or repeat interval"),
+  time: z.string().optional().describe("Daily run time in \"HH:MM\" format"),
+  cron: z.string().optional().describe("Cron expression (e.g. \"0 9 * * *\")"),
+}).openapi("ScheduleExpressionStruct");
+export type ScheduleExpressionStruct = z.infer<typeof scheduleExpressionStructSchema>;
+
+export const scheduleExpressionSchema = z.union([
+  z.string(),
+  scheduleExpressionStructSchema,
+]).openapi("ScheduleExpression");
+export type ScheduleExpression = z.infer<typeof scheduleExpressionSchema>;
+
+export const scheduledCmdSchema = z.object({
+  cmd: z.string(),
+  runAt: scheduleExpressionSchema,
+  onExit: onExitBehaviorSchema.optional(),
+  parser: z.string().optional(),
+}).openapi("ScheduledCmd");
+export type ScheduledCmd = z.infer<typeof scheduledCmdSchema>;
+
+export const buildExecuteStepSchema = z.object({
+  cmd: z.string().min(1).describe("Shell command to run as a separate RUN instruction (cacheable layer)").openapi({ example: "apt-get install -y curl" }),
+}).openapi("BuildExecuteStep");
+export type BuildExecuteStep = z.infer<typeof buildExecuteStepSchema>;

package/src/core/generic.ts

@@ -0,0 +1,38 @@
+import z from "zod";
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+
+extendZodWithOpenApi(z);
+
+export const resourceLimitsSchema = z.object({
+  memory_limit: z.string().optional().describe("e.g. \"2G\", \"512M\"").openapi({ example: "2G" }),
+  memory_reservation: z.string().optional().describe("Soft memory limit, e.g. \"1G\"").openapi({ example: "1G" }),
+  cpu_limit: z.string().optional().describe("e.g. \"2\", \"0.5\"").openapi({ example: "2" }),
+  cpu_reservation: z.string().optional().describe("Soft CPU limit, e.g. \"1\"").openapi({ example: "1" }),
+}).openapi("ResourceLimits");
+export type ResourceLimits = z.infer<typeof resourceLimitsSchema>;
+
+export const portMappingSchema = z.object({
+  container: z.int().min(1).max(65535).describe("Container port").openapi({ example: 3000 }),
+  host: z.int().min(0).max(65535).optional().describe("Host port. 0 or omitted means same as container port.").openapi({ example: 8080 }),
+}).openapi("PortMapping");
+export type PortMapping = z.infer<typeof portMappingSchema>;
+
+export const parsedOutputSchema = z.object({
+  success: z.boolean(),
+  data: z.record(z.string(), z.unknown()).optional().describe("Arbitrary structured data produced by the parser script"),
+}).openapi("ParsedOutput");
+export type ParsedOutput = z.infer<typeof parsedOutputSchema>;
+
+export const packageSpecSchema = z.object({
+  name: z.string(),
+  version: z.string().optional(),
+  args: z.array(z.string()).optional(),
+}).openapi("PackageSpec");
+export type PackageSpec = z.infer<typeof packageSpecSchema>;
+
+export const installGroupSchema = z.object({
+  packageManager: z.string().min(1).describe("Package manager to use (e.g. \"apt\", \"npm\", \"pip\")"),
+  packages: z.array(z.union([z.string(), packageSpecSchema])),
+  globalArgs: z.array(z.string()).optional().describe("Arguments passed to every package install invocation"),
+}).openapi("InstallGroup");
+export type InstallGroup = z.infer<typeof installGroupSchema>;

package/src/core/index.ts

@@ -0,0 +1,5 @@
+export * from './primitives.js';
+export * from './generic.js';
+export * from './execute.js';
+export * from './volumes.js';
+export * from './entities/index.js';

package/src/core/primitives.ts

@@ -0,0 +1,12 @@
+import z from "zod";
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+
+extendZodWithOpenApi(z);
+
+export const bigIntSchema = z
+.bigint()
+.describe("An integer between 3n and 5n")
+.openapi("BigInt", {
+    format: "int64",
+    type: "integer",
+});

package/src/core/volumes.ts

@@ -0,0 +1,124 @@
+// ---------------------------------------------------------------------------
+// Build-time volume mounts
+// ---------------------------------------------------------------------------
+
+import z from "zod";
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+
+extendZodWithOpenApi(z);
+
+export const fileContentSchema = z.object({
+  data: z.string().describe("File payload"),
+  encoding: z.string().optional().describe("Encoding of the data field (default \"utf-8\")"),
+}).openapi("FileContent");
+export type FileContent = z.infer<typeof fileContentSchema>;
+
+export const filePermissionsSchema = z.object({
+  read: z.int(),
+  write: z.int(),
+  execute: z.int(),
+}).openapi("FilePermissions");
+export type FilePermissions = z.infer<typeof filePermissionsSchema>;
+
+export const buildVolumeMountRegularSchema = z.object({
+  type: z.literal('regular'),
+  host_path: z.string().optional().describe("Absolute path on the host"),
+  container_path: z.string().optional().describe("Absolute path inside the container"),
+  read_only: z.boolean().optional(),
+}).openapi("BuildVolumeMountRegular");
+
+export const buildVolumeMountNewFileSchema = z.object({
+  type: z.literal('new-file'),
+  container_path: z.string().describe("Destination path inside the image (COPY semantics)"),
+  content: fileContentSchema,
+  owner: z.string().optional().describe("Unix owner string, e.g. \"root:root\""),
+  permissions: filePermissionsSchema.optional(),
+}).openapi("BuildVolumeMountNewFile");
+
+export const buildVolumeMountSchema = z.discriminatedUnion('type', [
+  buildVolumeMountRegularSchema,
+  buildVolumeMountNewFileSchema,
+]).openapi("BuildVolumeMount");
+export type BuildVolumeMount = z.infer<typeof buildVolumeMountSchema>;
+
+// ---------------------------------------------------------------------------
+// Run-time volume mounts
+// ---------------------------------------------------------------------------
+
+export const runVolumeMountRegularSchema = z.object({
+  type: z.literal('regular'),
+  host_path: z.string().optional(),
+  container_path: z.string().optional(),
+  read_only: z.boolean().optional(),
+}).openapi("RunVolumeMountRegular");
+
+export const runVolumeMountDockerSocketSchema = z.object({
+  type: z.literal('docker-socket'),
+  container_path: z.string().optional().describe("Mount point inside the container (defaults to /var/run/docker.sock)"),
+}).openapi("RunVolumeMountDockerSocket");
+
+export const runVolumeMountNewFileSchema = z.object({
+  type: z.literal('new-file'),
+  container_path: z.string(),
+  content: fileContentSchema,
+  owner: z.string().optional(),
+  permissions: filePermissionsSchema.optional(),
+}).openapi("RunVolumeMountNewFile");
+
+export const runVolumeMountNamedSchema = z.object({
+  type: z.literal('named'),
+  name: z.string().describe("Docker named volume name"),
+  container_path: z.string(),
+  read_only: z.boolean().optional(),
+}).openapi("RunVolumeMountNamed");
+
+export const runVolumeMountAnonymousSchema = z.object({
+  type: z.literal('anonymous'),
+  container_path: z.string(),
+}).openapi("RunVolumeMountAnonymous");
+
+export const runVolumeMountTmpfsSchema = z.object({
+  type: z.literal('tmpfs'),
+  container_path: z.string(),
+  size_mb: z.int().optional().describe("Size limit in MiB; absent means no limit"),
+}).openapi("RunVolumeMountTmpfs");
+
+export const runVolumeMountCopyInSchema = z.object({
+  type: z.literal('copy-in'),
+  host_path: z.string(),
+  container_path: z.string(),
+}).openapi("RunVolumeMountCopyIn");
+
+export const runVolumeMountCopyOutSchema = z.object({
+  type: z.literal('copy-out'),
+  container_path: z.string(),
+  host_path: z.string(),
+  changed_only: z.boolean().optional().describe("Copy only files changed since container start (uses docker diff)"),
+}).openapi("RunVolumeMountCopyOut");
+
+export const runVolumeMountSchema = z.discriminatedUnion('type', [
+  runVolumeMountRegularSchema,
+  runVolumeMountDockerSocketSchema,
+  runVolumeMountNewFileSchema,
+  runVolumeMountNamedSchema,
+  runVolumeMountAnonymousSchema,
+  runVolumeMountTmpfsSchema,
+  runVolumeMountCopyInSchema,
+  runVolumeMountCopyOutSchema,
+]).openapi("RunVolumeMount");
+export type RunVolumeMount = z.infer<typeof runVolumeMountSchema>;
+
+export const volumeMountSchema = z.object({
+  type: z.string().optional().describe("Optional mount type. Use \"docker-socket\" for Docker socket mounts.").openapi({ example: "docker-socket" }),
+  host_path: z.string().describe("Absolute path on the host").openapi({ example: "/var/run/docker.sock" }),
+  container_path: z.string().optional().describe("Absolute path inside the container (may be omitted for docker-socket mounts)").openapi({ example: "/var/run/docker.sock" }),
+  read_only: z.boolean().describe("Whether the mount is read-only"),
+}).openapi("VolumeMount");
+export type VolumeMount = z.infer<typeof volumeMountSchema>;
+
+export const namedVolumeMountSchema = z.object({
+  volume_name: z.string().min(1).describe("Docker named volume name").openapi({ example: "figulus-cache-nodejs" }),
+  container_path: z.string().min(1).describe("Mount point inside the container").openapi({ example: "/root/.npm" }),
+  read_only: z.boolean(),
+}).openapi("NamedVolumeMount");
+export type NamedVolumeMount = z.infer<typeof namedVolumeMountSchema>;

package/src/engine/deprecated/index.ts

@@ -0,0 +1 @@
+export * from './run-request.js';

package/src/engine/deprecated/run-request.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import { namedVolumeMountSchema, volumeMountSchema } from '../../core/volumes.js';
+import { parsedOutputSchema, portMappingSchema, resourceLimitsSchema } from '../../core/generic.js';
+
+extendZodWithOpenApi(z);
+
+export const jobStatusSchema = z.enum([
+  'pending',
+  'running',
+  'completed',
+  'failed',
+  'timeout',
+  'awaiting_cleanup',
+]).openapi("JobStatus");
+export type JobStatus = z.infer<typeof jobStatusSchema>;
+
+export const runRequestSchema = z.object({
+  job_id: z.string().min(1).describe("Unique identifier for this job").openapi({ example: "job-abc123" }),
+  image: z.string().min(1).describe("Docker image to run").openapi({ example: "node:20-alpine" }),
+  command: z.array(z.string()).optional().describe("Command and arguments to execute").openapi({ example: ["node","index.js"] }),
+  environment: z.record(z.string(), z.string()).optional().describe("Environment variables"),
+  volumes: z.array(volumeMountSchema).optional().describe("Bind mounts (host path → container path)"),
+  named_volumes: z.array(namedVolumeMountSchema).optional().describe("Docker named volume mounts"),
+  resources: resourceLimitsSchema.optional(),
+  timeout: z.int().positive().max(86400).optional().describe("Execution timeout in seconds (default 300)").openapi({ example: 300 }),
+  parser_script: z.string().optional().describe("Full JavaScript parser source code for structured output parsing"),
+  root_dir: z.string().optional().describe("Root directory for file:// parser resolution"),
+  env_files: z.array(z.string()).optional().describe("Paths to .env files to load"),
+  secrets: z.record(z.string(), z.string()).optional().describe("Secret references: env_name → \"vault:path#field\""),
+  extra_hosts: z.array(z.string()).optional().describe("Extra /etc/hosts entries, e.g. \"host.docker.internal:host-gateway\""),
+  network_mode: z.string().optional().describe("Docker network mode: \"host\", \"bridge\", \"none\", etc.").openapi({ example: "bridge" }),
+  working_dir: z.string().optional().describe("Working directory inside the container (overrides Dockerfile WORKDIR)").openapi({ example: "/app" }),
+  ports: z.array(portMappingSchema).optional().describe("Port mappings (container port → host port)"),
+}).openapi("RunRequest");
+export type RunRequest = z.infer<typeof runRequestSchema>;
+
+export const runResponseSchema = z.object({
+  job_id: z.string().openapi({ example: "job-abc123" }),
+  status: jobStatusSchema,
+  message: z.string().optional().openapi({ example: "Job accepted and queued" }),
+  container_id: z.string().optional().describe("Docker container ID, present once container is created"),
+  exit_code: z.int().nullable().optional().describe("Container exit code, present on completion"),
+  stdout: z.string().optional(),
+  stderr: z.string().optional(),
+  parsed_output: parsedOutputSchema.optional(),
+  started_at: z.iso.datetime().optional().openapi({ format: "date-time" }),
+  completed_at: z.iso.datetime().optional().openapi({ format: "date-time" }),
+  duration: z.number().optional().describe("Execution duration in seconds").openapi({ format: "double" }),
+  command: z.array(z.string()).optional().describe("Original command from the request"),
+  final_command: z.array(z.string()).optional().describe("Actual command executed after any wrapping or modification"),
+}).openapi("RunResponse");
+export type RunResponse = z.infer<typeof runResponseSchema>;

package/src/engine/dry-run.ts

@@ -0,0 +1,14 @@
+import z from "zod";
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import { volumeMountSchema } from "../core/volumes.js";
+
+extendZodWithOpenApi(z);
+
+export const dryRunResponseSchema = z.object({
+  command: z.array(z.string()).describe("Original command from the request"),
+  final_command: z.array(z.string()).describe("Actual command that would be executed"),
+  image: z.string(),
+  working_dir: z.string(),
+  volumes: z.array(volumeMountSchema).optional().describe("Volume mounts with computed container paths"),
+}).openapi("DryRunResponse");
+export type DryRunResponse = z.infer<typeof dryRunResponseSchema>;

package/src/engine/health.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+
+extendZodWithOpenApi(z);
+
+export const healthResponseSchema = z.object({
+  status: z.enum(['healthy', 'unhealthy']),
+  docker_api: z.string().optional().describe("Docker daemon info string, present when healthy").openapi({ example: "Docker v29.3.0, 12 containers" }),
+  message: z.string().optional().describe("Error detail, present when unhealthy").openapi({ example: "Docker daemon unreachable: connection refused" }),
+}).openapi("HealthResponse");
+export type HealthResponse = z.infer<typeof healthResponseSchema>;

package/src/engine/images.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+
+extendZodWithOpenApi(z);
+
+export const buildImageRequestSchema = z.object({
+  spec: z.record(z.string(), z.unknown()).describe("Figspec build specification describing the image to build"),
+  platform: z.string().optional().describe("Target platform, e.g. \"linux/amd64\", \"linux/arm64\"").openapi({ example: "linux/amd64" }),
+  parser_script: z.string().optional().describe("JavaScript parser source for build output (resolved by server)"),
+  root_dir: z.string().optional().describe("Root directory for file:// parser resolution"),
+}).openapi("BuildImageRequest");
+export type BuildImageRequest = z.infer<typeof buildImageRequestSchema>;
+
+export const buildImageResponseSchema = z.object({
+  image_tag: z.string().min(1).describe("Fully qualified image tag").openapi({ example: "localhost:5000/figulus:sha256-abc123de" }),
+  hash: z.string().min(1).describe("Content-addressable hash of the spec").openapi({ example: "abc123defgh456" }),
+  cached: z.boolean().describe("true if the image was already in cache (no build needed)"),
+  message: z.string().optional().openapi({ example: "Image built successfully" }),
+}).openapi("BuildImageResponse");
+export type BuildImageResponse = z.infer<typeof buildImageResponseSchema>;
+
+export const pruneImagesRequestSchema = z.object({
+  retention_days: z.int().min(1).optional().describe("Images unused for longer than this many days are removed (overrides query param)"),
+  all: z.boolean().optional().describe("When true, also prune all unused Docker images (not just Figulus-managed)"),
+}).openapi("PruneImagesRequest");
+export type PruneImagesRequest = z.infer<typeof pruneImagesRequestSchema>;
+
+export const pruneImagesResponseSchema = z.object({
+  removed: z.int().describe("Number of Figulus-managed images removed"),
+  bytes_freed: z.int().describe("Bytes freed by Figulus GC").openapi({ format: "int64" }),
+  mb_freed: z.number().describe("Megabytes freed by Figulus GC").openapi({ format: "double" }),
+  message: z.string(),
+  docker_images_pruned: z.int().optional().describe("Number of Docker-native images pruned (only present when all=true)"),
+  docker_bytes_freed: z.int().optional().describe("Bytes freed by Docker-native image prune (only present when all=true)").openapi({ format: "int64" }),
+}).openapi("PruneImagesResponse");
+export type PruneImagesResponse = z.infer<typeof pruneImagesResponseSchema>;
+
+export const pruneCacheResponseSchema = z.object({
+  freed_bytes: z.int(),
+});
+export type PruneCacheResponse = z.infer<typeof pruneCacheResponseSchema>;
+
+export const extractArtifactsRequestSchema = z.object({
+  container_id: z.string().min(1).describe("Docker container ID to extract from").openapi({ example: "a1b2c3d4e5f6" }),
+  container_path: z.string().min(1).describe("Absolute path inside the container to extract").openapi({ example: "/app/dist" }),
+  host_path: z.string().min(1).describe("Absolute path on the host to extract files into").openapi({ example: "/tmp/artifacts" }),
+}).openapi("ExtractArtifactsRequest");
+export type ExtractArtifactsRequest = z.infer<typeof extractArtifactsRequestSchema>;
+
+export const extractArtifactsResponseSchema = z.object({
+  container_id: z.string(),
+  container_path: z.string(),
+  host_path: z.string(),
+  files_count: z.int().optional().describe("Number of files extracted"),
+  total_bytes: z.int().optional().describe("Total bytes extracted").openapi({ format: "int64" }),
+  message: z.string(),
+}).openapi("ExtractArtifactsResponse");
+export type ExtractArtifactsResponse = z.infer<typeof extractArtifactsResponseSchema>;

package/src/engine/index.ts

@@ -0,0 +1,8 @@
+export * from './response.js';
+export * from './dry-run.js';
+export * from './health.js';
+export * from './images.js';
+export * from './sessions.js';
+export * from './volumes.js';
+export * from './paths/index.js';
+export * from './deprecated/index.js';