cli-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://github.com/zdmilot/Library-Manager/blob/main/cli-schema.json",
  "title": "HxLibPkg Package Specification",
  "description": "JSON specification file used by `node cli.js create-package --spec <file>` to build a .hxlibpkg library package. File paths inside this document are resolved relative to the directory containing the spec file itself. Unknown properties are preserved to support forward compatibility with future application versions.",
  "type": "object",

  "required": ["author", "version", "venus_compatibility", "description", "library_files"],

  "properties": {

    "library_name": {
      "type": "string",
      "minLength": 1,
      "description": "Name of the library. If omitted, auto-detected from the first .hsl, .hs_, or .smt file in library_files (in that priority order). Must not contain path separators.",
      "examples": ["MyVenusLibrary", "ML600_CustomMethods"]
    },

    "author": {
      "type": "string",
      "minLength": 3,
      "maxLength": 500,
      "description": "Full name of the library author. Required.",
      "examples": ["Jane Smith", "Automation Team"]
    },

    "organization": {
      "type": "string",
      "description": "Author's organization or company. Optional.",
      "examples": ["Hamilton Bonaduz AG", "Acme Pharma"]
    },

    "version": {
      "type": "string",
      "minLength": 1,
      "description": "Library version number string. Required. No specific format is enforced, but semantic versioning is recommended.",
      "examples": ["1.0.0", "2.3.1", "1.0"]
    },

    "venus_compatibility": {
      "type": "string",
      "description": "VENUS software version compatibility range or description. Required.",
      "examples": ["4.7+", "5.0 - 6.x", "4.4 and above", "6.1"]
    },

    "description": {
      "type": "string",
      "description": "Human-readable description of the library's purpose, features, and usage notes. Required.",
      "examples": ["Provides high-level pipetting helpers for the ML600 syringe pump."]
    },

    "release_notes": {
      "type": "string",
      "description": "Free-text release notes describing what is included, new, changed, or fixed in this version. Stored in the package manifest and displayed during import preview. Optional.",
      "examples": ["Initial release with pipetting helpers and error recovery routines.", "- Added 96-well plate support\n- Fixed volume tracking for small volumes\n- Improved error messages"]
    },

    "release_notes_pdf": {
      "type": "string",
      "description": "Relative path to a .pdf file containing release notes for this version. The PDF is embedded in the package as base64 and displayed in the import preview. Optional; restricted to OEM/developer use.",
      "examples": ["ReleaseNotes_v2.0.pdf"]
    },

    "github_url": {
      "type": "string",
      "format": "uri",
      "description": "URL to the library's GitHub repository. Optional.",
      "examples": ["https://github.com/user/venus-library"]
    },

    "tags": {
      "type": "array",
      "description": "Searchable keyword tags for the library. Optional.",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "uniqueItems": true,
      "examples": [
        ["pipetting", "ML600", "syringe"],
        ["labware", "96-well"]
      ]
    },

    "category": {
      "type": "string",
      "enum": ["General Utility", "Device Driver"],
      "default": "General Utility",
      "description": "Category for marketplace grouping. Used by the Library Store to group packages. Defaults to 'General Utility' if omitted.",
      "examples": ["General Utility", "Device Driver"]
    },

    "device_compatibility": {
      "type": "array",
      "description": "List of Hamilton instruments this library is compatible with. Optional. Valid values: 'Nimbus', 'STAR Line', 'Vantage'.",
      "items": {
        "type": "string",
        "enum": ["Nimbus", "STAR Line", "Vantage"]
      },
      "uniqueItems": true,
      "examples": [
        ["Nimbus"],
        ["STAR Line", "Vantage"],
        ["Nimbus", "STAR Line", "Vantage"]
      ]
    },

    "library_image": {
      "type": "string",
      "description": "Path to an image file used as the library icon (.png, .jpg, .bmp, .svg, .gif, .ico). Resolved relative to the spec file directory. If omitted, the packager looks for a .bmp whose basename matches library_name among library_files.",
      "examples": ["images/MyLib_icon.png", "../icons/logo.svg"]
    },

    "library_files": {
      "type": "array",
      "description": "Paths to the library payload files (.hsl, .hs_, .hsi, .smt, .stp, .dll, .bmp, and any other distributed files). At least one file is required. Paths are resolved relative to the spec file directory. Executable, script, registry, and shortcut file types (.exe, .bat, .cmd, .ps1, .vbs, .reg, .lnk, .msi, etc.) are restricted and will be rejected.",
      "minItems": 1,
      "items": {
        "type": "string",
        "minLength": 1
      },
      "examples": [
        ["src/MyLibrary.hsl", "src/MyLibrary.hs_", "src/MyLibrary.hsi", "src/MyLibrary.bmp"]
      ]
    },

    "demo_method_files": {
      "type": "array",
      "description": "Paths to demo / example method files (.hsl, .lay, .med, etc.) that illustrate how to use the library. Installed separately under the Methods directory. Optional. Executable, script, registry, and shortcut file types are restricted and will be rejected.",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "examples": [
        ["demo/Demo_MyLibrary.hsl", "demo/Demo_MyLibrary.lay"]
      ]
    },
    "labware_files": {
      "type": "array",
      "description": "Paths to labware definition files (.rck, .ctr, .tml, .dck, .lay) that ship with the library. Each entry is a relative path with an optional subdirectory under the Labware root. File paths must be purely relative — no drive letters, no '//' or '\\\\', and must begin with one of the three allowed roots (Library, Methods, Labware) or be bare filenames. Installed under the Hamilton Labware directory. Optional. Executable, script, registry, and shortcut file types are restricted and will be rejected.",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "examples": [
        ["labware/MyCustomPlate.rck", "labware/Plates/MyDeepWell.ctr"]
      ]
    },
    "help_files": {
      "type": "array",
      "description": "Basenames of .chm help files that ship with the library. These are installed in the library folder alongside library_files but tracked separately so the UI can surface them for quick access. If omitted, .chm files are auto-detected from library_files during import.",
      "items": {
        "type": "string",
        "minLength": 1,
        "pattern": "\\.chm$"
      },
      "examples": [
        ["MyVenusLibrary.chm"]
      ]
    },

    "default_help_file": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\.chm$",
      "description": "Basename of the .chm help file to open by default when the user clicks Help on the library card. Only meaningful when the library contains multiple .chm help files. When set, clicking Help opens this file directly instead of showing a menu of all help files. Must match a basename in help_files (or a .chm in library_files).",
      "examples": [
        "MyVenusLibrary.chm"
      ]
    },

    "com_register_dlls": {
      "type": "array",
      "description": "Basenames (not full paths) of DLL files listed in library_files that must be registered as COM objects using RegAsm.exe /codebase. Administrator rights are required at import time. DLL names must exactly match basenames of entries in library_files.",
      "items": {
        "type": "string",
        "minLength": 1,
        "pattern": "\\.dll$"
      },
      "examples": [
        ["MyLibraryCOM.dll"],
        ["HelperA.dll", "HelperB.dll"]
      ]
    },

    "install_to_library_root": {
      "type": "boolean",
      "default": true,
      "description": "When true (default), library files are installed directly into the Library root directory. When false with a custom_install_subdir specified, files are installed into that subdirectory. The user can override this setting at import time."
    }

  },

  "additionalProperties": true,

  "examples": [
    {
      "library_name": "MyVenusLibrary",
      "author": "Jane Smith",
      "organization": "Acme Pharma",
      "version": "1.0.0",
      "venus_compatibility": "4.7+",
      "description": "My example Hamilton VENUS library.",
      "tags": ["example", "venus"],
      "library_image": "MyVenusLibrary.png",
      "library_files": [
        "MyVenusLibrary.hsl",
        "MyVenusLibrary.hs_",
        "MyVenusLibrary.hsi",
        "MyVenusLibrary.bmp"
      ],
      "demo_method_files": [
        "demo/Demo_MyVenusLibrary.hsl"
      ],
      "help_files": [
        "MyVenusLibrary.chm"
      ],
      "com_register_dlls": []
    }
  ]
}