id          = "jenkins-job-builder"
name        = "Jenkins Job Builder"
homepage    = "https://docs.openstack.org/infra/jenkins-job-builder/"
description = "Manage Jenkins jobs with YAML or JSON definitions"
executables      = ["jenkins-jobs"]
platforms   = ["macos", "linux"]

[dotfiles]

# The upstream execution documentation gives ~/.config/jenkins_jobs/
# jenkins_jobs.ini as the first default config location (before the script
# directory and /etc). The file can contain Jenkins API passwords/tokens.
# https://jenkins-job-builder.readthedocs.io/en/stable/execution.html
paths = []
secret = ["~/.config/jenkins_jobs/jenkins_jobs.ini"]
side_effect = false

[commands]
format = 1
label = "Jenkins Job Builder"
description = "Render or push Jenkins job definitions from YAML/JSON. Only the test and update commands are covered; server credentials, delete commands and plugin-info export are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = false, short_attached = false, short_bundles = true }

[[commands.subcommand]]
path = ["test"]
label = "Test and render XML"
description = "Expand job definitions and print or write the resulting Jenkins XML without contacting the server."

[[commands.subcommand.source]]
id = "man"
kind = "manual"
url = "https://manpages.debian.org/unstable/jenkins-job-builder/jenkins-jobs.1.en.html"
revision = "2026-10-27"
evidence = """
  path                  colon-separated list of paths to YAML files or
                        directories
  names                 name(s) of job(s)
  -r, --recursive       look for yaml files recursively
  -x, --exclude EXCLUDE
                        paths to exclude when using recursive search, uses
                        standard globbing.
  --config-xml          use alternative output file layout using config.xml
                        files
  -o OUTPUT_DIR         path to output XML
"""

[[commands.subcommand.field]]
id = "path"
label = "Definitions path"
description = "YAML/JSON file or directory; several paths can be joined with a colon."
type = "path"
path = { kind = "any", role = "input" }
position = 0
sources = ["man"]

[[commands.subcommand.field]]
id = "names"
label = "Job names"
description = "Limit the run to these jobs; empty means all."
type = "string"
position = 1
multiple = true
sources = ["man"]

[[commands.subcommand.field]]
id = "recursive"
label = "Search recursively"
type = "boolean"
option = ["--recursive", "-r"]
sources = ["man"]

[[commands.subcommand.field]]
id = "exclude"
label = "Exclude paths"
type = "string"
option = ["--exclude", "-x"]
multiple = true
sources = ["man"]

[[commands.subcommand.field]]
id = "output_dir"
label = "Output directory"
description = "Write XML files here instead of standard output."
type = "path"
option = ["-o"]
path = { kind = "directory", role = "output", must_exist = false }
sources = ["man"]

[[commands.subcommand.field]]
id = "config_xml"
label = "config.xml layout"
type = "boolean"
option = ["--config-xml"]
sources = ["man"]

[[commands.subcommand.task]]
id = "preview"
label = "Preview XML"
fields = ["path", "names", "recursive"]
required = ["path"]

[[commands.subcommand.task]]
id = "write"
label = "Write XML to a directory"
fields = ["path", "names", "recursive", "output_dir", "config_xml"]
required = ["path", "output_dir"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["path", "names", "recursive", "output_dir"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["exclude", "config_xml"]

[[commands.subcommand]]
path = ["update"]
label = "Update jobs on Jenkins"
description = "Push job definitions to the Jenkins server configured in jenkins_jobs.ini. Updating changes jobs on the server."

[[commands.subcommand.source]]
id = "man"
kind = "manual"
url = "https://manpages.debian.org/unstable/jenkins-job-builder/jenkins-jobs.1.en.html"
revision = "2026-10-27"
evidence = """
  path                  colon-separated list of paths to YAML files or
                        directories
  names                 name(s) of job(s)
  -r, --recursive       look for yaml files recursively
  -x, --exclude EXCLUDE
                        paths to exclude when using recursive search, uses
                        standard globbing.
  --delete-old          delete obsolete jobs
  --workers N_WORKERS   number of workers to use, 0 for autodetection and 1
                        for just one worker.
  --existing-only       update existing jobs only
  --enabled-only        update enabled jobs only
  -j, --jobs-only       update only jobs
  -v, --views-only      update only views
"""

[[commands.subcommand.field]]
id = "path"
label = "Definitions path"
type = "path"
path = { kind = "any", role = "input" }
position = 0
sources = ["man"]

[[commands.subcommand.field]]
id = "names"
label = "Job names"
description = "Limit the run to these jobs; empty means all."
type = "string"
position = 1
multiple = true
sources = ["man"]

[[commands.subcommand.field]]
id = "recursive"
label = "Search recursively"
type = "boolean"
option = ["--recursive", "-r"]
sources = ["man"]

[[commands.subcommand.field]]
id = "exclude"
label = "Exclude paths"
type = "string"
option = ["--exclude", "-x"]
multiple = true
sources = ["man"]

[[commands.subcommand.field]]
id = "delete_old"
label = "Delete obsolete jobs"
description = "Removes jobs from Jenkins that are no longer defined."
type = "boolean"
option = ["--delete-old"]
effect = "delete"
sources = ["man"]

[[commands.subcommand.field]]
id = "workers"
label = "Workers"
description = "0 autodetects; 1 uses a single worker."
type = "integer"
option = ["--workers"]
sources = ["man"]

[[commands.subcommand.field]]
id = "existing_only"
label = "Existing jobs only"
type = "boolean"
option = ["--existing-only"]
sources = ["man"]

[[commands.subcommand.field]]
id = "enabled_only"
label = "Enabled jobs only"
type = "boolean"
option = ["--enabled-only"]
sources = ["man"]

[[commands.subcommand.field]]
id = "jobs_only"
label = "Jobs only"
type = "boolean"
option = ["--jobs-only", "-j"]
sources = ["man"]

[[commands.subcommand.field]]
id = "views_only"
label = "Views only"
type = "boolean"
option = ["--views-only", "-v"]
sources = ["man"]

[[commands.subcommand.task]]
id = "update"
label = "Update jobs"
fields = ["path", "names", "recursive", "workers"]
required = ["path"]

[[commands.subcommand.task]]
id = "sync"
label = "Update and delete obsolete"
fields = ["path", "names", "recursive", "delete_old"]
required = ["path"]
set = { delete_old = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["path", "names", "recursive", "jobs_only", "views_only"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["exclude", "delete_old", "workers", "existing_only", "enabled_only"]