Recipe Schema

{
  "name": "string",
  "baseImage": "string",
  "features": ["string"],
  "packages": ["string"],
  "custom_packages": [CustomPackage],
  "extra_repos": ["string"],
  "package_overrides": [PackageOverride],
  "services": [ServiceConfig],
  "users": [UserConfig],
  "security": SecurityConfig,
  "desktop": DesktopConfig,
  "startupScripts": [ScriptConfig],
  "tests": [TestConfig]
}

"name": "production-web-server"

"baseImage": "debian-bookworm"

"features": ["ssh", "docker", "firewall", "security-hardening"]

"packages": ["htop", "vim", "tmux", "curl", "jq"]

"custom_packages": [
  {
    "name": "my-agent",
    "git_url": "https://github.com/myorg/my-agent.git",
    "branch": "main"
  }
]

"extra_repos": [
  "deb http://packages.example.com/debian stable main"
]

"package_overrides": [
  {
    "name": "nano",
    "action": "replace",
    "replacement": "neovim"
  }
]

"services": [
  {
    "name": "ssh",
    "config": {
      "port": 2222
    }
  }
]

"users": [
  {
    "username": "admin",
    "groups": ["sudo"]
  }
]

"security": {
  "hardeningLevel": "strict"
}

"desktop": {
  "theme": "dark"
}

"startupScripts": [
  {
    "name": "init",
    "script": "#!/bin/bash\necho 'done'"
  }
]

"tests": [
  {
    "description": "Verify app",
    "assertions": [...]
  }
]

interface ServiceConfig {
  name: string;
  config: Record<string, any>;
}

interface SSHConfig {
  port?: number;              // Default: 22
  allow_root?: boolean;       // Default: false
  disable_password_auth?: boolean; // Default: false
  timeout?: number;           // Default: 120
  client_alive_interval?: number; // Default: 60
  max_auth_tries?: number;    // Default: 6
}

interface UserConfig {
  username: string;           // Required
  shell?: string;             // Default: /bin/bash
  groups?: string[];          // Additional groups
  home?: string;              // Home directory
  comment?: string;           // User description
}

interface SecurityConfig {
  hardeningLevel?: 'minimal' | 'standard' | 'strict';
  auditLogging?: boolean;
  automaticUpdates?: boolean;
}

interface DesktopConfig {
  theme?: 'light' | 'dark' | 'system';
  accentColor?: string;
  wallpaper?: string;
  favorites?: string[];
  fonts?: FontConfig;
  power?: PowerConfig;
  extensions?: string[];
}
 
interface FontConfig {
  interface?: string;
  document?: string;
  monospace?: string;
}
 
interface PowerConfig {
  screenBlankTimeout?: number;
  suspendOnIdle?: boolean;
  lidCloseAction?: string;
}

interface ScriptConfig {
  name: string;               // Required
  script: string;             // Required (with shebang)
  runAs?: string;             // Default: root
  timeout?: number;           // Max seconds
}

interface TestConfig {
  description: string;
  assertions: Assertion[];
}
 
interface Assertion {
  type: string;
  params: Record<string, any>;
}

interface CustomPackage {
  name: string;               // Required — display name
  git_url: string;            // Required — Git repository URL
  branch?: string;            // Default: "main"
}

interface PackageOverride {
  name: string;               // Required — package name
  action: 'add' | 'remove' | 'replace'; // Required
  replacement?: string;       // Required for 'replace' action
}

{
  "name": "secure-production-server",
  "baseImage": "debian-bookworm",
  "features": [
    "ssh",
    "docker",
    "firewall",
    "security-hardening"
  ],
  "services": [
    {
      "name": "ssh",
      "config": {
        "port": 2222,
        "allow_root": false,
        "disable_password_auth": true,
        "timeout": 300,
        "client_alive_interval": 30,
        "max_auth_tries": 3
      }
    }
  ],
  "users": [
    {
      "username": "admin",
      "shell": "/bin/bash",
      "groups": ["sudo", "docker"],
      "comment": "System administrator"
    },
    {
      "username": "deploy",
      "shell": "/bin/bash",
      "groups": ["docker"],
      "comment": "Deployment account"
    }
  ],
  "security": {
    "hardeningLevel": "strict",
    "auditLogging": true,
    "automaticUpdates": true
  },
  "startupScripts": [
    {
      "name": "register-server",
      "script": "#!/bin/bash\ncurl -X POST https://mgmt.example.com/register -d \"hostname=$(hostname)\""
    }
  ],
  "tests": [
    {
      "description": "Verify security configuration",
      "assertions": [
        {
          "type": "service_running",
          "params": { "service": "ssh" }
        },
        {
          "type": "port_listening",
          "params": { "port": 2222 }
        },
        {
          "type": "user_exists",
          "params": {
            "username": "admin",
            "groups": ["sudo", "docker"]
          }
        },
        {
          "type": "file_contains",
          "params": {
            "path": "/etc/ssh/sshd_config",
            "content": "PermitRootLogin no"
          }
        }
      ]
    }
  ]
}