@figulus/schema 0.4.0-alpha-dev

package/src/run-request.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import {
+  JobStatusSchema,
+  ParsedOutputSchema,
+  ResourceLimitsSchema,
+  VolumeMountSchema,
+  NamedVolumeMountSchema,
+  PortMappingSchema,
+} from './shared.js';
+
+export const RunRequestSchema = z.object({
+  job_id: z.string().min(1),
+  image: z.string().min(1),
+  command: z.array(z.string()).optional(),
+  environment: z.record(z.string()).optional(),
+  volumes: z.array(VolumeMountSchema).optional(),
+  named_volumes: z.array(NamedVolumeMountSchema).optional(),
+  resources: ResourceLimitsSchema.optional(),
+  timeout: z.number().int().positive().max(86400).optional(),
+  parser_script: z.string().optional(),
+  root_dir: z.string().optional(),
+  env_files: z.array(z.string()).optional(),
+  secrets: z.record(z.string()).optional(),
+  extra_hosts: z.array(z.string()).optional(),
+  network_mode: z.string().optional(),
+  working_dir: z.string().optional(),
+  ports: z.array(PortMappingSchema).optional(),
+});
+export type RunRequest = z.infer<typeof RunRequestSchema>;
+
+export const RunResponseSchema = z.object({
+  job_id: z.string(),
+  status: JobStatusSchema,
+  message: z.string().optional(),
+  container_id: z.string().optional(),
+  exit_code: z.number().int().nullable().optional(),
+  stdout: z.string().optional(),
+  stderr: z.string().optional(),
+  parsed_output: ParsedOutputSchema.optional(),
+  started_at: z.string().datetime().optional(),
+  completed_at: z.string().datetime().optional(),
+  duration: z.number().optional(),
+  command: z.array(z.string()).optional(),
+  final_command: z.array(z.string()).optional(),
+});
+export type RunResponse = z.infer<typeof RunResponseSchema>;
+
+export const DryRunResponseSchema = z.object({
+  command: z.array(z.string()),
+  final_command: z.array(z.string()),
+  image: z.string(),
+  working_dir: z.string(),
+  volumes: z.array(VolumeMountSchema).optional(),
+});
+export type DryRunResponse = z.infer<typeof DryRunResponseSchema>;

package/src/session.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import {
+  SessionStatusSchema,
+  ParsedOutputSchema,
+  VolumeMountSchema,
+  NamedVolumeMountSchema,
+  PortMappingSchema,
+} from './shared.js';
+
+export const SessionConfigSchema = z.object({
+  working_dir: z.string().optional(),
+  environment: z.record(z.string()).optional(),
+  parser_script: z.string().optional(),
+  volumes: z.array(VolumeMountSchema).optional(),
+  named_volumes: z.array(NamedVolumeMountSchema).optional(),
+  init_cmd: z.array(z.string()).optional(),
+  destroy_cmd: z.array(z.string()).optional(),
+  ports: z.array(PortMappingSchema).optional(),
+  start_cmd: z.array(z.string()).optional(),
+  auto_cleanup: z.boolean().optional(),
+});
+export type SessionConfig = z.infer<typeof SessionConfigSchema>;
+
+export const CreateSessionRequestSchema = z.object({
+  image_tag: z.string().min(1),
+  ttl: z.number().int().positive().optional(),
+  config: SessionConfigSchema.optional(),
+  block_until_complete: z.boolean().optional(),
+});
+export type CreateSessionRequest = z.infer<typeof CreateSessionRequestSchema>;
+
+export const CreateSessionResponseSchema = z.object({
+  session_id: z.string(),
+  container_id: z.string(),
+  status: SessionStatusSchema,
+  created_at: z.string().datetime(),
+  ports: z.array(PortMappingSchema).optional(),
+  exit_code: z.number().int().optional(),
+  stdout: z.string().optional(),
+  stderr: z.string().optional(),
+});
+export type CreateSessionResponse = z.infer<typeof CreateSessionResponseSchema>;
+
+export const GetSessionResponseSchema = z.object({
+  session_id: z.string(),
+  container_id: z.string(),
+  image_tag: z.string(),
+  status: SessionStatusSchema,
+  created_at: z.string().datetime(),
+  last_used_at: z.string().datetime(),
+  ttl: z.number().int(),
+  ports: z.array(PortMappingSchema).optional(),
+});
+export type GetSessionResponse = z.infer<typeof GetSessionResponseSchema>;
+
+export const RunInSessionRequestSchema = z.object({
+  command: z.array(z.string()).min(1),
+  timeout: z.number().int().positive().max(86400).optional(),
+  parser_script: z.string().optional(),
+  working_dir: z.string().optional(),
+});
+export type RunInSessionRequest = z.infer<typeof RunInSessionRequestSchema>;
+
+export const RunInSessionResponseSchema = z.object({
+  run_id: z.string(),
+  exit_code: z.number().int(),
+  stdout: z.string(),
+  stderr: z.string(),
+  parsed_output: z.record(z.unknown()).optional(),
+  duration: z.number(),
+});
+export type RunInSessionResponse = z.infer<typeof RunInSessionResponseSchema>;
+
+export const GetRunResponseSchema = z.object({
+  run_id: z.string(),
+  session_id: z.string(),
+  command: z.array(z.string()),
+  exit_code: z.number().int(),
+  stdout: z.string(),
+  stderr: z.string(),
+  parsed_output: z.record(z.unknown()).optional(),
+  started_at: z.string().datetime(),
+  completed_at: z.string().datetime(),
+  duration: z.number(),
+});
+export type GetRunResponse = z.infer<typeof GetRunResponseSchema>;
+
+export const SyncFileRequestSchema = z.object({
+  targetPath: z.string().min(1),
+  content: z.string().min(1),
+  encoding: z.enum(['base64', 'utf8']).default('base64'),
+});
+export type SyncFileRequest = z.infer<typeof SyncFileRequestSchema>;
+
+export const SyncFileResponseSchema = z.object({
+  success: z.boolean(),
+  path: z.string(),
+  bytes_written: z.number().int(),
+  message: z.string().optional(),
+});
+export type SyncFileResponse = z.infer<typeof SyncFileResponseSchema>;

package/src/shared.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+export const JobStatusSchema = z.enum([
+  'pending',
+  'running',
+  'completed',
+  'failed',
+  'timeout',
+  'awaiting_cleanup',
+]);
+export type JobStatus = z.infer<typeof JobStatusSchema>;
+
+export const SessionStatusSchema = z.enum(['active', 'idle', 'expired']);
+export type SessionStatus = z.infer<typeof SessionStatusSchema>;
+
+export const ParsedOutputSchema = z.object({
+  success: z.boolean(),
+  data: z.record(z.unknown()).optional(),
+});
+export type ParsedOutput = z.infer<typeof ParsedOutputSchema>;
+
+export const ResourceLimitsSchema = z.object({
+  memory_limit: z.string().optional(),
+  memory_reservation: z.string().optional(),
+  cpu_limit: z.string().optional(),
+  cpu_reservation: z.string().optional(),
+});
+export type ResourceLimits = z.infer<typeof ResourceLimitsSchema>;
+
+export const VolumeMountSchema = z.object({
+  type: z.string().optional(),
+  host_path: z.string(),
+  container_path: z.string().optional(),
+  read_only: z.boolean(),
+});
+export type VolumeMount = z.infer<typeof VolumeMountSchema>;
+
+export const NamedVolumeMountSchema = z.object({
+  volume_name: z.string().min(1),
+  container_path: z.string().min(1),
+  read_only: z.boolean(),
+});
+export type NamedVolumeMount = z.infer<typeof NamedVolumeMountSchema>;
+
+export const PortMappingSchema = z.object({
+  container: z.number().int().min(1).max(65535),
+  host: z.number().int().min(0).max(65535).optional(),
+});
+export type PortMapping = z.infer<typeof PortMappingSchema>;
+
+export const ErrorResponseSchema = z.object({
+  error: z.string(),
+  message: z.string(),
+  code: z.number().int(),
+});
+export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;

package/src/volume.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+
+export const EnsureVolumeRequestSchema = z.object({
+  volume_name: z.string().min(1),
+  driver: z.string().optional(),
+  labels: z.record(z.string()).optional(),
+});
+export type EnsureVolumeRequest = z.infer<typeof EnsureVolumeRequestSchema>;
+
+export const EnsureVolumeResponseSchema = z.object({
+  volume_name: z.string(),
+  created: z.boolean(),
+  message: z.string().optional(),
+});
+export type EnsureVolumeResponse = z.infer<typeof EnsureVolumeResponseSchema>;
+
+export const VolumeInfoSchema = z.object({
+  name: z.string(),
+  driver: z.string(),
+  mountpoint: z.string(),
+  created_at: z.string(),
+  labels: z.record(z.string()).optional(),
+  scope: z.string(),
+  size_bytes: z.number().int().optional(),
+});
+export type VolumeInfo = z.infer<typeof VolumeInfoSchema>;
+
+export const ListVolumesResponseSchema = z.object({
+  volumes: z.array(VolumeInfoSchema),
+  count: z.number().int(),
+});
+export type ListVolumesResponse = z.infer<typeof ListVolumesResponseSchema>;
+
+export const DeleteVolumeResponseSchema = z.object({
+  volume_name: z.string(),
+  message: z.string(),
+});
+export type DeleteVolumeResponse = z.infer<typeof DeleteVolumeResponseSchema>;
+
+export const PruneVolumesRequestSchema = z.object({
+  filters: z.record(z.array(z.string())).optional(),
+});
+export type PruneVolumesRequest = z.infer<typeof PruneVolumesRequestSchema>;
+
+export const PruneVolumesResponseSchema = z.object({
+  volumes_deleted: z.array(z.string()),
+  space_reclaimed: z.number().int(),
+  message: z.string(),
+});
+export type PruneVolumesResponse = z.infer<typeof PruneVolumesResponseSchema>;

package/tests/figspec.test.ts

@@ -0,0 +1,383 @@
+import { describe, it, expect } from 'vitest';
+import {
+  figSpecSchema,
+  figSpecBuildStandaloneSchema,
+  figSpecBuildWithBaseSpecSchema,
+  figSpecRunSchema,
+  runVolumeMountSchema,
+  buildVolumeMountSchema,
+  installGroupSchema,
+  onExitBehaviorSchema,
+  executeMainCmdSchema,
+} from '../src/figspec.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const minimalMainCmd = { cmd: 'node server.js' };
+const minimalExecute = { main: minimalMainCmd };
+const minimalRun = { execute: minimalExecute };
+const minimalBuildStandalone = { baseImage: 'ubuntu:24.04' };
+const minimalSpec = { schemaVersion: '1', build: minimalBuildStandalone };
+
+// ---------------------------------------------------------------------------
+// Top-level FigSpec
+// ---------------------------------------------------------------------------
+
+describe('figSpecSchema', () => {
+  it('accepts a minimal spec (baseImage + execute.main.cmd only)', () => {
+    expect(() => figSpecSchema.parse(minimalSpec)).not.toThrow();
+  });
+
+  it('accepts a spec with run section', () => {
+    expect(() =>
+      figSpecSchema.parse({ ...minimalSpec, run: minimalRun }),
+    ).not.toThrow();
+  });
+
+  it('accepts build as a string specName reference', () => {
+    expect(() =>
+      figSpecSchema.parse({ schemaVersion: '1', build: 'my-base-spec' }),
+    ).not.toThrow();
+  });
+
+  it('accepts build as an array of specName strings', () => {
+    expect(() =>
+      figSpecSchema.parse({ schemaVersion: '1', build: ['stage-a', 'stage-b'] }),
+    ).not.toThrow();
+  });
+
+  it('rejects missing schemaVersion', () => {
+    expect(() => figSpecSchema.parse({ build: minimalBuildStandalone })).toThrow();
+  });
+
+  it('rejects missing build', () => {
+    expect(() => figSpecSchema.parse({ schemaVersion: '1' })).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Build spec variants
+// ---------------------------------------------------------------------------
+
+describe('figSpecBuildStandaloneSchema', () => {
+  it('accepts minimal standalone spec', () => {
+    expect(() => figSpecBuildStandaloneSchema.parse(minimalBuildStandalone)).not.toThrow();
+  });
+
+  it('accepts full standalone spec with packages and env', () => {
+    const full = {
+      baseImage: 'node:20-alpine',
+      schemaVersion: '1',
+      specName: 'my-app',
+      packagesToInstall: [
+        { packageManager: 'npm', packages: ['lodash', { name: 'express', version: '4.18.0' }] },
+      ],
+      env: { NODE_ENV: 'production' },
+      workDir: '/app',
+      user: 'node',
+      platform: 'linux/amd64',
+    };
+    expect(() => figSpecBuildStandaloneSchema.parse(full)).not.toThrow();
+  });
+
+  it('rejects missing baseImage', () => {
+    expect(() => figSpecBuildStandaloneSchema.parse({ workDir: '/app' })).toThrow();
+  });
+});
+
+describe('figSpecBuildWithBaseSpecSchema', () => {
+  it('accepts spec with baseSpec and no baseImage', () => {
+    expect(() =>
+      figSpecBuildWithBaseSpecSchema.parse({ baseSpec: 'node-base' }),
+    ).not.toThrow();
+  });
+
+  it('accepts spec with both baseSpec and baseImage override', () => {
+    expect(() =>
+      figSpecBuildWithBaseSpecSchema.parse({ baseSpec: 'node-base', baseImage: 'custom:latest' }),
+    ).not.toThrow();
+  });
+
+  it('rejects missing baseSpec', () => {
+    expect(() =>
+      figSpecBuildWithBaseSpecSchema.parse({ baseImage: 'ubuntu:24.04' }),
+    ).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Run spec
+// ---------------------------------------------------------------------------
+
+describe('figSpecRunSchema', () => {
+  it('accepts minimal run spec', () => {
+    expect(() => figSpecRunSchema.parse(minimalRun)).not.toThrow();
+  });
+
+  it('accepts full run spec with all fields', () => {
+    const full = {
+      execute: {
+        startup: [{ cmd: 'npm install', async: false }],
+        main: { cmd: 'node server.js', parser: 'console.log(JSON.stringify({success:true}))' },
+        shutdown: [{ cmd: 'node cleanup.js' }],
+        scheduled: [{ cmd: 'node cron.js', runAt: '0 9 * * *' }],
+      },
+      env: { PORT: '3000' },
+      secrets: { DB_PASS: 'vault:secrets/db#password' },
+      workDir: '/app',
+      user: 'node',
+      ports: [{ container: 3000, host: 8080 }],
+    };
+    expect(() => figSpecRunSchema.parse(full)).not.toThrow();
+  });
+
+  it('rejects missing execute', () => {
+    expect(() => figSpecRunSchema.parse({ env: { X: '1' } })).toThrow();
+  });
+
+  it('rejects execute without main', () => {
+    expect(() =>
+      figSpecRunSchema.parse({ execute: { startup: [] } }),
+    ).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Volume discriminated unions
+// ---------------------------------------------------------------------------
+
+describe('runVolumeMountSchema — type discriminator', () => {
+  it('accepts regular bind mount', () => {
+    expect(() =>
+      runVolumeMountSchema.parse({ type: 'regular', host_path: '/tmp/src', container_path: '/app' }),
+    ).not.toThrow();
+  });
+
+  it('accepts docker-socket mount', () => {
+    expect(() =>
+      runVolumeMountSchema.parse({ type: 'docker-socket' }),
+    ).not.toThrow();
+  });
+
+  it('accepts named volume mount', () => {
+    expect(() =>
+      runVolumeMountSchema.parse({ type: 'named', name: 'my-vol', container_path: '/data' }),
+    ).not.toThrow();
+  });
+
+  it('accepts anonymous volume mount', () => {
+    expect(() =>
+      runVolumeMountSchema.parse({ type: 'anonymous', container_path: '/tmp/cache' }),
+    ).not.toThrow();
+  });
+
+  it('accepts tmpfs mount', () => {
+    expect(() =>
+      runVolumeMountSchema.parse({ type: 'tmpfs', container_path: '/run', size_mb: 128 }),
+    ).not.toThrow();
+  });
+
+  it('accepts copy-in mount', () => {
+    expect(() =>
+      runVolumeMountSchema.parse({ type: 'copy-in', host_path: '/host/src', container_path: '/app/src' }),
+    ).not.toThrow();
+  });
+
+  it('accepts copy-out mount', () => {
+    expect(() =>
+      runVolumeMountSchema.parse({ type: 'copy-out', container_path: '/app/dist', host_path: '/host/dist', changed_only: true }),
+    ).not.toThrow();
+  });
+
+  it('accepts new-file injection', () => {
+    expect(() =>
+      runVolumeMountSchema.parse({
+        type: 'new-file',
+        container_path: '/app/.env',
+        content: { data: 'KEY=value' },
+      }),
+    ).not.toThrow();
+  });
+
+  it('rejects invalid type discriminator', () => {
+    expect(() =>
+      runVolumeMountSchema.parse({ type: 'invalid-type', container_path: '/x' }),
+    ).toThrow();
+  });
+
+  it('rejects named mount missing required name field', () => {
+    expect(() =>
+      runVolumeMountSchema.parse({ type: 'named', container_path: '/data' }),
+    ).toThrow();
+  });
+});
+
+describe('buildVolumeMountSchema — type discriminator', () => {
+  it('accepts regular build mount', () => {
+    expect(() =>
+      buildVolumeMountSchema.parse({ type: 'regular', host_path: '/src', container_path: '/app' }),
+    ).not.toThrow();
+  });
+
+  it('accepts new-file build mount', () => {
+    expect(() =>
+      buildVolumeMountSchema.parse({
+        type: 'new-file',
+        container_path: '/etc/app.conf',
+        content: { data: 'debug=true', encoding: 'utf-8' },
+      }),
+    ).not.toThrow();
+  });
+
+  it('rejects invalid type discriminator', () => {
+    expect(() =>
+      buildVolumeMountSchema.parse({ type: 'docker-socket' }),
+    ).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// onExit polymorphism
+// ---------------------------------------------------------------------------
+
+describe('onExitBehaviorSchema', () => {
+  it('accepts null', () => {
+    expect(() => onExitBehaviorSchema.parse(null)).not.toThrow();
+  });
+
+  it('accepts "persist"', () => {
+    expect(() => onExitBehaviorSchema.parse('persist')).not.toThrow();
+  });
+
+  it('accepts "shutdown"', () => {
+    expect(() => onExitBehaviorSchema.parse('shutdown')).not.toThrow();
+  });
+
+  it('accepts arbitrary command string', () => {
+    expect(() => onExitBehaviorSchema.parse('node cleanup.js')).not.toThrow();
+  });
+
+  it('accepts exit-code dispatch table', () => {
+    expect(() =>
+      onExitBehaviorSchema.parse([
+        { exitCode: 0, cmd: 'shutdown' },
+        { exitCode: 1, cmd: 'node retry.js' },
+      ]),
+    ).not.toThrow();
+  });
+
+  it('rejects invalid value (number)', () => {
+    expect(() => onExitBehaviorSchema.parse(42)).toThrow();
+  });
+});
+
+describe('executeMainCmdSchema — onExit field', () => {
+  it('accepts cmd only', () => {
+    expect(() => executeMainCmdSchema.parse({ cmd: 'node app.js' })).not.toThrow();
+  });
+
+  it('accepts null onExit', () => {
+    expect(() => executeMainCmdSchema.parse({ cmd: 'node app.js', onExit: null })).not.toThrow();
+  });
+
+  it('rejects invalid onExit value', () => {
+    expect(() => executeMainCmdSchema.parse({ cmd: 'node app.js', onExit: 99 })).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// InstallGroup
+// ---------------------------------------------------------------------------
+
+describe('installGroupSchema', () => {
+  it('accepts packages as strings', () => {
+    expect(() =>
+      installGroupSchema.parse({ packageManager: 'apt', packages: ['curl', 'git'] }),
+    ).not.toThrow();
+  });
+
+  it('accepts packages as PackageSpec objects', () => {
+    expect(() =>
+      installGroupSchema.parse({
+        packageManager: 'npm',
+        packages: [{ name: 'express', version: '4.18.0', args: ['--save'] }],
+      }),
+    ).not.toThrow();
+  });
+
+  it('accepts mixed string and PackageSpec packages', () => {
+    expect(() =>
+      installGroupSchema.parse({
+        packageManager: 'pip',
+        packages: ['requests', { name: 'boto3', version: '1.34.0' }],
+        globalArgs: ['--quiet'],
+      }),
+    ).not.toThrow();
+  });
+
+  it('rejects empty packageManager', () => {
+    expect(() =>
+      installGroupSchema.parse({ packageManager: '', packages: ['curl'] }),
+    ).toThrow();
+  });
+
+  it('rejects missing packages array', () => {
+    expect(() =>
+      installGroupSchema.parse({ packageManager: 'apt' }),
+    ).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Full realistic spec
+// ---------------------------------------------------------------------------
+
+describe('full realistic figspec', () => {
+  it('passes a spec with startup, named volume, copy-out, and parser', () => {
+    const spec = {
+      schemaVersion: '1',
+      specName: 'my-service',
+      build: {
+        baseImage: 'node:20-alpine',
+        packagesToInstall: [
+          { packageManager: 'npm', packages: ['express', { name: 'pg', version: '8.11.0' }] },
+        ],
+        workDir: '/app',
+        volumes: [
+          { type: 'regular', host_path: '/src', container_path: '/app', read_only: true },
+        ],
+      },
+      run: {
+        execute: {
+          startup: [{ cmd: 'npm ci', async: false }],
+          main: {
+            cmd: 'node dist/server.js',
+            onExit: [
+              { exitCode: 0, cmd: 'shutdown' },
+              { exitCode: 1, cmd: 'node scripts/retry.js' },
+            ],
+            parser: 'return { pid: line.match(/pid (\\d+)/)?.[1] }',
+          },
+          shutdown: [{ cmd: 'node scripts/drain.js' }],
+          scheduled: [
+            {
+              cmd: 'node scripts/cleanup.js',
+              runAt: { cron: '0 2 * * *' },
+              onExit: 'shutdown',
+            },
+          ],
+        },
+        env: { NODE_ENV: 'production', PORT: '3000' },
+        secrets: { DATABASE_URL: 'vault:secrets/prod#db_url' },
+        volumes: [
+          { type: 'named', name: 'node-cache', container_path: '/root/.npm' },
+          { type: 'copy-out', container_path: '/app/logs', host_path: '/host/logs', changed_only: true },
+        ],
+        ports: [{ container: 3000, host: 3000 }],
+      },
+    };
+    expect(() => figSpecSchema.parse(spec)).not.toThrow();
+  });
+});