@invarn/cibuild 1.0.0 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.dev.md +141 -0
  2. package/README.md +99 -86
  3. package/dist/cli.cjs +1 -1
  4. package/package.json +8 -3
package/README.dev.md ADDED
@@ -0,0 +1,141 @@
1
+ # cibuild
2
+
3
+ Lightweight CI/CD pipeline runner for Android and iOS projects. Run your pipelines locally or on a remote runner using a simple YAML format.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ brew tap invarnhq/cibuild
9
+ brew install cibuild
10
+ ```
11
+
12
+ This installs two commands: `ci` and `cibuild` (both identical).
13
+
14
+ ## Getting Started
15
+
16
+ There are three ways to set up a pipeline in your project:
17
+
18
+ ### 1. Create (recommended)
19
+
20
+ Auto-detects your platform (iOS/Android), picks recommended build settings, and collects secrets from disk — fully non-interactive:
21
+
22
+ ```bash
23
+ ci init --create
24
+ ```
25
+
26
+ ### 2. Interactive
27
+
28
+ Walk through an interactive wizard to choose between creating or importing a pipeline:
29
+
30
+ ```bash
31
+ ci init
32
+ ```
33
+
34
+ ### 3. Import
35
+
36
+ Import an existing YAML pipeline file into your project:
37
+
38
+ ```bash
39
+ ci init --import path/to/pipeline.yml
40
+ ```
41
+
42
+ All three methods scaffold the `.ci/pipelines/` directory, validate dependencies, and add runtime files to `.gitignore`.
43
+
44
+ For the full pipeline YAML format, step catalog, and examples, see [SPEC.md](SPEC.md).
45
+
46
+ ## Commands
47
+
48
+ ```bash
49
+ ci init # Interactive setup wizard
50
+ ci init --create # Auto-create pipeline (non-interactive)
51
+ ci init --import <path> # Import YAML pipeline (non-interactive)
52
+ ci build # Generate a standard pipeline for the current project
53
+ ci run <path> [-w <name>] # Run locally (development mode)
54
+ ci run <path> [-w <name>] --production # Run on remote runner (production)
55
+ ci run <path> [-w <name>] --validate-only # Validate only, don't execute
56
+ ci run <path> [-w <name>] --skip-validation # Skip validation, run with interactive prompts
57
+ ci validate <path> [-w <name>] # Validate pipeline (alias for --validate-only)
58
+ ci detect-platform <path> [-w <name>] # Detect platform from YAML pipeline
59
+ ci edit <path> [-w <name>] # View pipeline and edit step inputs
60
+ ci secrets add <var_name> <path> [-w <name>] # Add a secret (prompted interactively)
61
+ ci --help # Show help
62
+ ```
63
+
64
+ ## Supported Formats
65
+
66
+ - `.yml` / `.yaml` — YAML pipeline files
67
+ - `.ts` — TypeScript pipeline files
68
+
69
+ ---
70
+
71
+ ## Development
72
+
73
+ ### Prerequisites
74
+
75
+ - Node.js 20+
76
+ - npm
77
+
78
+ ### Setup
79
+
80
+ ```bash
81
+ npm install
82
+ ```
83
+
84
+ ### Build (development)
85
+
86
+ Compiles TypeScript via `tsc` into `dist/src/`:
87
+
88
+ ```bash
89
+ npm run build
90
+ ```
91
+
92
+ ### Watch mode
93
+
94
+ ```bash
95
+ npm run dev
96
+ ```
97
+
98
+ ### Tests
99
+
100
+ ```bash
101
+ npm test
102
+ ```
103
+
104
+ ---
105
+
106
+ ## Release Builds
107
+
108
+ Two independent build pipelines exist depending on the distribution target.
109
+
110
+ ### Homebrew (native binary)
111
+
112
+ Bundles with esbuild, then compiles to a standalone macOS binary via `pkg`. No obfuscation — `pkg` embeds the JS inside the binary, which already protects the source. Obfuscation is intentionally skipped here because it encodes `require()` string arguments, breaking `pkg`'s static analysis.
113
+
114
+ ```bash
115
+ npm run release
116
+ # Outputs:
117
+ # dist/cibuild-macos-arm64.tar.gz
118
+ # dist/cibuild-macos-x64.tar.gz
119
+ ```
120
+
121
+ ### npm (obfuscated JS)
122
+
123
+ Bundles with esbuild, then obfuscates with `javascript-obfuscator` (base64 string encoding). Produces a single self-contained `.cjs` file.
124
+
125
+ ```bash
126
+ npm run build:npm
127
+ # Outputs:
128
+ # dist/cli.cjs (minified + string-obfuscated)
129
+ ```
130
+
131
+ ### Releasing a new version
132
+
133
+ Tagging and pushing a version tag triggers the GitHub Actions release workflow, which:
134
+ 1. Runs `npm run release` to build both macOS binaries
135
+ 2. Creates a release on `invarnhq/cibuild` with the binaries attached
136
+ 3. Auto-updates `Formula/cibuild.rb` in the public tap repo with the new version and SHA256 checksums
137
+
138
+ ```bash
139
+ git tag v1.0.0
140
+ git push origin v1.0.0
141
+ ```
package/README.md CHANGED
@@ -1,141 +1,154 @@
1
1
  # cibuild
2
2
 
3
- Lightweight CI/CD pipeline runner for Android and iOS projects. Run your pipelines locally or on a remote runner using a simple YAML format.
3
+ Lightweight CI/CD pipeline runner for Android and iOS projects. Define pipelines in YAML, run them locally or on a remote runner.
4
4
 
5
5
  ## Install
6
6
 
7
7
  ```bash
8
- brew tap invarnhq/cibuild
9
- brew install cibuild
8
+ npm install -g @invarn/cibuild
10
9
  ```
11
10
 
12
- This installs two commands: `ci` and `cibuild` (both identical).
11
+ This installs two identical commands: `ci` and `cibuild`.
13
12
 
14
- ## Getting Started
15
-
16
- There are three ways to set up a pipeline in your project:
13
+ ## GitHub Actions
17
14
 
18
- ### 1. Create (recommended)
15
+ Use cibuild directly in your GitHub Actions workflows:
19
16
 
20
- Auto-detects your platform (iOS/Android), picks recommended build settings, and collects secrets from disk — fully non-interactive:
17
+ ```yaml
18
+ name: CI
19
+ on: [push, pull_request]
21
20
 
22
- ```bash
23
- ci init --create
21
+ jobs:
22
+ build:
23
+ runs-on: macos-latest
24
+ environment: cibuild
25
+ steps:
26
+ - uses: actions/checkout@v4
27
+ - uses: invarnhq/cibuild@v1
28
+ with:
29
+ workflow: release
24
30
  ```
25
31
 
26
- ### 2. Interactive
32
+ ### Action Inputs
27
33
 
28
- Walk through an interactive wizard to choose between creating or importing a pipeline:
29
-
30
- ```bash
31
- ci init
32
- ```
34
+ | Input | Required | Default | Description |
35
+ |---|---|---|---|
36
+ | `pipeline` | No | Auto-discover | Path to pipeline YAML file |
37
+ | `workflow` | No | First workflow | Workflow name within the pipeline |
38
+ | `version` | No | `latest` | cibuild version to install |
33
39
 
34
- ### 3. Import
40
+ ### Secrets in GitHub Actions
35
41
 
36
- Import an existing YAML pipeline file into your project:
42
+ Upload your local secrets to a GitHub Environment, then reference them in your workflow:
37
43
 
38
44
  ```bash
39
- ci init --import path/to/pipeline.yml
45
+ ci secrets upload --env cibuild
40
46
  ```
41
47
 
42
- All three methods scaffold the `.ci/pipelines/` directory, validate dependencies, and add runtime files to `.gitignore`.
43
-
44
- For the full pipeline YAML format, step catalog, and examples, see [SPEC.md](SPEC.md).
45
-
46
- ## Commands
47
-
48
- ```bash
49
- ci init # Interactive setup wizard
50
- ci init --create # Auto-create pipeline (non-interactive)
51
- ci init --import <path> # Import YAML pipeline (non-interactive)
52
- ci build # Generate a standard pipeline for the current project
53
- ci run <path> [-w <name>] # Run locally (development mode)
54
- ci run <path> [-w <name>] --production # Run on remote runner (production)
55
- ci run <path> [-w <name>] --validate-only # Validate only, don't execute
56
- ci run <path> [-w <name>] --skip-validation # Skip validation, run with interactive prompts
57
- ci validate <path> [-w <name>] # Validate pipeline (alias for --validate-only)
58
- ci detect-platform <path> [-w <name>] # Detect platform from YAML pipeline
59
- ci edit <path> [-w <name>] # View pipeline and edit step inputs
60
- ci secrets add <var_name> <path> [-w <name>] # Add a secret (prompted interactively)
61
- ci --help # Show help
48
+ ```yaml
49
+ jobs:
50
+ build:
51
+ runs-on: macos-latest
52
+ environment: cibuild
53
+ env:
54
+ CIBUILD_S__SLACK_WEBHOOK: ${{ secrets.CIBUILD_S__SLACK_WEBHOOK }}
55
+ CIBUILD_SW__RELEASE__KEYSTORE_PASS: ${{ secrets.CIBUILD_SW__RELEASE__KEYSTORE_PASS }}
56
+ steps:
57
+ - uses: actions/checkout@v4
58
+ - uses: invarnhq/cibuild@v1
59
+ with:
60
+ workflow: release
62
61
  ```
63
62
 
64
- ## Supported Formats
65
-
66
- - `.yml` / `.yaml` — YAML pipeline files
67
- - `.ts` — TypeScript pipeline files
63
+ The action automatically maps GitHub context to cibuild environment variables (`GIT_BRANCH`, `GIT_COMMIT`, `BUILD_NUMBER`, `BUILD_URL`).
68
64
 
69
- ---
70
-
71
- ## Development
72
-
73
- ### Prerequisites
65
+ ## Getting Started
74
66
 
75
- - Node.js 20+
76
- - npm
67
+ ### Option 1. Auto-create (recommended)
77
68
 
78
- ### Setup
69
+ From your project root, let cibuild scan the project and generate a pipeline with recommended defaults:
79
70
 
80
71
  ```bash
81
- npm install
72
+ ci init --create
82
73
  ```
83
74
 
84
- ### Build (development)
75
+ This auto-detects the platform (iOS/Android), configures build settings, and collects secrets from disk — fully non-interactive, works with AI agents and scripts.
85
76
 
86
- Compiles TypeScript via `tsc` into `dist/src/`:
87
-
88
- ```bash
89
- npm run build
90
- ```
77
+ ### Option 2. Interactive wizard
91
78
 
92
- ### Watch mode
79
+ Walk through prompts to configure your pipeline step by step:
93
80
 
94
81
  ```bash
95
- npm run dev
82
+ ci init
96
83
  ```
97
84
 
98
- ### Tests
85
+ ### Option 3. Import existing pipeline
86
+
87
+ If you already have a pipeline YAML file:
99
88
 
100
89
  ```bash
101
- npm test
90
+ ci init --import path/to/pipeline.yml
102
91
  ```
103
92
 
104
- ---
93
+ All three methods scaffold the `.ci/pipelines/` directory, validate dependencies, and set up `.gitignore`.
94
+
95
+ ### Customize
105
96
 
106
- ## Release Builds
97
+ cibuild works best when you start with `ci init --create` and build on top of the generated pipeline. The full pipeline format, step catalog, and customization rules are in the spec.
107
98
 
108
- Two independent build pipelines exist depending on the distribution target.
99
+ Tell your AI coding agent:
109
100
 
110
- ### Homebrew (native binary)
101
+ > Set up and customize CI/CD pipelines for this project using cibuild according to the following spec: https://github.com/invarnhq/cibuild/blob/main/SPEC.md
111
102
 
112
- Bundles with esbuild, then compiles to a standalone macOS binary via `pkg`. No obfuscation — `pkg` embeds the JS inside the binary, which already protects the source. Obfuscation is intentionally skipped here because it encodes `require()` string arguments, breaking `pkg`'s static analysis.
103
+ ### Run
113
104
 
114
105
  ```bash
115
- npm run release
116
- # Outputs:
117
- # dist/cibuild-macos-arm64.tar.gz
118
- # dist/cibuild-macos-x64.tar.gz
106
+ ci run # Run the default pipeline
107
+ ci run .ci/pipelines/cibuild.yml -w release # Run a specific workflow
119
108
  ```
120
109
 
121
- ### npm (obfuscated JS)
110
+ ## Commands
122
111
 
123
- Bundles with esbuild, then obfuscates with `javascript-obfuscator` (base64 string encoding). Produces a single self-contained `.cjs` file.
112
+ | Command | Description |
113
+ |---|---|
114
+ | `ci init` | Interactive setup wizard |
115
+ | `ci init --create` | Auto-create pipeline (non-interactive) |
116
+ | `ci init --import <path>` | Import YAML pipeline (non-interactive) |
117
+ | `ci build` | Generate a standard pipeline for the current project |
118
+ | `ci run <path> [-w <name>]` | Run pipeline locally (development mode) |
119
+ | `ci run <path> [-w <name>] --production` | Run on remote runner (production) |
120
+ | `ci run <path> [-w <name>] --validate-only` | Validate only, don't execute |
121
+ | `ci run <path> [-w <name>] --skip-validation` | Skip validation, run with interactive prompts |
122
+ | `ci validate <path> [-w <name>]` | Validate pipeline (alias for --validate-only) |
123
+ | `ci detect-platform <path> [-w <name>]` | Detect platform from YAML pipeline |
124
+ | `ci edit <path> [-w <name>]` | View pipeline and edit step inputs |
125
+ | `ci secrets add <var> <path> [-w <name>]` | Add a secret (prompted interactively) |
126
+ | `ci secrets add <var> <path> --file <file>` | Add a secret from a file |
127
+ | `ci --help` | Show help |
128
+
129
+ ### Options
130
+
131
+ | Flag | Description |
132
+ |---|---|
133
+ | `-w, --workflow <name>` | Select a workflow (YAML pipelines only, defaults to first) |
134
+ | `--production` | Execute on remote runner after validation (vs local) |
135
+ | `--validate-only` | Run validation only, don't execute pipeline |
136
+ | `--skip-validation` | Skip pre-execution validation (for development) |
137
+
138
+ ## Secrets
139
+
140
+ Secrets are stored locally in `.cibuild-secrets.json` and never committed.
124
141
 
125
142
  ```bash
126
- npm run build:npm
127
- # Outputs:
128
- # dist/cli.cjs (minified + string-obfuscated)
143
+ ci secrets add KEYSTORE_PASSWORD pipeline.yml
144
+ ci secrets add KEYSTORE_BASE64 pipeline.yml --file release.keystore
145
+ ci secrets add SLACK_WEBHOOK pipeline.yml -w release
129
146
  ```
130
147
 
131
- ### Releasing a new version
148
+ ## Requirements
132
149
 
133
- Tagging and pushing a version tag triggers the GitHub Actions release workflow, which:
134
- 1. Runs `npm run release` to build both macOS binaries
135
- 2. Creates a release on `invarnhq/cibuild` with the binaries attached
136
- 3. Auto-updates `Formula/cibuild.rb` in the public tap repo with the new version and SHA256 checksums
150
+ - macOS or Linux (Node.js 18+ for npm install)
151
+ - Android projects: JDK, Android SDK
152
+ - iOS projects: macOS with Xcode (CocoaPods optional)
137
153
 
138
- ```bash
139
- git tag v1.0.0
140
- git push origin v1.0.0
141
- ```
154
+ Run `ci init` from your project root to check all dependencies automatically.