gen-circleci-orb 0.0.21

Generate a CircleCI orb to provide the facilities offered by a CLI program
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176

# gen-circleci-orb

Generate a CircleCI orb to provide the facilities offered by a CLI program.

[![Crates.io](https://img.shields.io/crates/v/gen-circleci-orb.svg)](https://crates.io/crates/gen-circleci-orb)
[![Documentation](https://docs.rs/gen-circleci-orb/badge.svg)](https://docs.rs/gen-circleci-orb)
[![License](https://img.shields.io/crates/l/gen-circleci-orb.svg)](https://github.com/jerus-org/gen-circleci-orb#license)

## Overview

**gen-circleci-orb** reads the `--help` output of any CLI binary and generates a complete
CircleCI orb: one command and one job per subcommand, an executor, a Dockerfile, and optionally
the CI configuration to keep the orb in sync with the binary automatically.

## Installation

```bash
cargo binstall gen-circleci-orb
# or
cargo install gen-circleci-orb
```

## Quick start

**Step 1 — generate orb source for your binary (run from project root):**

```bash
gen-circleci-orb generate \
  --binary my-tool \
  --orb-namespace my-org
```

This writes orb source into an `orb/` subdirectory (the default `--orb-dir`):
- `orb/src/@orb.yml` — orb metadata (version, description)
- `orb/src/commands/<subcommand>.yml` — one per leaf subcommand
- `orb/src/jobs/<subcommand>.yml` — one per leaf subcommand
- `orb/src/executors/default.yml` — Docker executor with a `tag` parameter
- `orb/Dockerfile` — image that pre-installs your binary

The orb source is always isolated in its own subdirectory so it cannot be confused
with existing project source. If the target directory already exists but doesn't
contain a CircleCI orb, an error is raised.

**Step 2 — wire orb generation into CI:**

```bash
# Public orb in a single namespace
gen-circleci-orb init \
  --binary my-tool \
  --public-orb-namespace my-org \
  --docker-namespace my-docker-org \
  --build-workflow validation \
  --release-workflow release \
  --requires-job common-tests \
  --release-after-job release-my-tool

# Mixed: production namespace public, pre-production namespace private
gen-circleci-orb init \
  --binary my-tool \
  --public-orb-namespace my-org \
  --private-orb-namespace my-org-preprod \
  --docker-namespace my-docker-org \
  --build-workflow validation \
  --release-workflow release \
  --requires-job common-tests \
  --release-after-job release-my-tool
```

This patches `.circleci/config.yml` and `.circleci/release.yml` to add:
- A `regenerate-orb` job that re-runs `generate` on every build
- `orb-tools/pack` + `orb-tools/review` steps to verify the generated orb
- A `build-container` job in the release workflow to publish the Docker image
- An `orb-tools/publish` step to publish the orb to the CircleCI registry

## `generate` reference

```
gen-circleci-orb generate [OPTIONS] --binary <BINARY> --orb-namespace <NAMESPACE>

Options:
  --binary <BINARY>               Binary to introspect (must be on PATH)
  --orb-namespace <NAMESPACE>     CircleCI orb namespace (repeatable)
  --output <DIR>                  Project root directory [default: .]
  --orb-dir <DIR>                 Orb subdirectory within --output [default: orb]
  --install-method <METHOD>       binstall | apt [default: binstall]
  --base-image <IMAGE>            Docker base image [default: debian:12-slim]
  --home-url <URL>                Home URL for orb registry display
  --source-url <URL>              Source URL for orb registry display
  --dry-run                       Print planned files, write nothing
```

## `init` reference

```
gen-circleci-orb init [OPTIONS] --binary <BINARY>
                                 --public-orb-namespace <NS> | --private-orb-namespace <NS>
                                 --docker-namespace <NS>
                                 --build-workflow <WF> --release-workflow <WF>

Required:
  --binary <BINARY>                   Binary to introspect (must be on PATH)
  --public-orb-namespace <NS>         CircleCI orb namespace, registered public (repeatable)
  --private-orb-namespace <NS>        CircleCI orb namespace, registered private (repeatable)
  --docker-namespace <NS>             Docker Hub (or registry) namespace for the container image
  --build-workflow <WF>           Validation workflow name to patch
  --release-workflow <WF>         Release workflow name to patch

Options:
  --requires-job <JOB>            Job regenerate-orb should require
  --release-after-job <JOB>       Job build-container should require
  --orb-dir <DIR>                 Orb output directory [default: orb]
  --ci-dir <DIR>                  CircleCI config directory [default: .circleci]
  --orb-tools-version <VER>       circleci/orb-tools pin [default: 12.3.3]
  --docker-orb-version <VER>      circleci/docker pin [default: 3.2.0]
  --docker-context <CTX>          CircleCI context for Docker Hub credentials [default: docker-credentials]
  --orb-context <CTX>             CircleCI context for orb publish credentials [default: orb-publishing]
  --mcp                           Wire in toolkit/build_mcp_server (jerus-org toolkit only)
  --dry-run                       Print planned changes, write nothing
```

## Generated artifacts

| File | Description |
|------|-------------|
| `src/@orb.yml` | Orb metadata: version 2.1, description, display URLs |
| `src/executors/default.yml` | Docker executor with `tag` parameter (default: latest) |
| `src/commands/<name>.yml` | Reusable command with all parameters and a `run:` step |
| `src/jobs/<name>.yml` | Job wrapping the command: checkout + delegate |
| `Dockerfile` | `FROM <base-image>` + install step (binstall or apt) |

### Parameter required vs optional

A parameter is required in the generated orb only if the CLI itself requires it — read
from the `Usage:` line: flags outside any `[...]` group are required; flags inside
`[OPTIONS]` are optional.

Optional parameters always have a `default:` so orb consumers can omit them:
- boolean flags default to `false`
- string/enum flags with a CLI default use that value
- string flags with no CLI default use `""` (empty string)

The run step uses CircleCI mustache conditionals for optional parameters so blank or false
values are not forwarded as empty flags to the binary.

### Excluded flags

Two flags are always excluded from the generated output:
- `-h/--help` — clap built-in
- `-V/--version` **with no `<VALUE>` metavar** — clap built-in (prints binary version)

An application flag named `--version` that accepts a value (e.g. `--version <VERSION>`)
is **not** excluded. However, reusing the `-V/--version` name for application purposes
is discouraged: it conflicts with the widely-understood convention and requires
special-case handling in any tool that parses `--help` output. Prefer an explicit name
such as `--crate-version` or `--output-version` instead.

## Environment requirements

| Tool | Purpose |
|------|---------|
| The target binary | Must be on `PATH` for `--help` introspection |
| `circleci` CLI | To pack/validate the generated orb (optional, for local testing) |

## License

Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
[MIT license](LICENSE-MIT) at your option.

## Contributing

See the [Contributing Guide](https://github.com/jerus-org/gen-circleci-orb/blob/main/CONTRIBUTING.md)
and [Code of Conduct](https://github.com/jerus-org/gen-circleci-orb/blob/main/CODE_OF_CONDUCT.md).

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.