Repository navigation
Manifests
A build type describes how one kind of project is built: which files identify it, what the user fills in, and which shell commands run on the target machine.
A build type is one JSON file at manifest/<id>.json, created next to config.json. The file name is the type id (manifest/xcode.json → xcode), and the file carries two answers: include says "is this project of my kind", build says "how do I build it".
Eight types ship with the binary:
| id | display name | platform |
|---|---|---|
xcode |
Xcode (iOS) | xcode |
xcode-ipa |
Xcode (iOS Unsigned IPA) | xcode |
rust-native |
Rust (Cargo) | rust |
flutter-ios |
Flutter for iOS | flutter |
flutter-android |
Flutter for Android | flutter |
kotlin-multiplatform-ios |
Kotlin Multiplatform for iOS | kotlin-multiplatform-ios |
gradle-android |
Gradle (Android) | gradle |
cmake-native |
CMake (C/C++) | cmake |
The directory is seeded once and then yours. On first launch, if manifest/ does not exist, the daemon creates it and copies the templates in. It never does that again: deleting a file does not bring it back, and editing one is never overwritten. A pre-existing variety/ directory is renamed in place to manifest/ at startup, so nothing is copied or lost.
template: true in the WebUI and CLI list only means "this file has the same name as a shipped template, so it can be restored". It is not special treatment.
Only displayName and build are required. Everything else may be omitted and falls back to a default.
| Field | Type | Required | Meaning |
|---|---|---|---|
displayName |
string | yes (non-empty) | Name shown in lists and pickers. |
platform |
string | no | Open label: xcode / gradle / flutter / dart / rust and anything else. It is never validated, so a new platform needs no code change. |
include.paths |
string[] | no (empty never matches) | Detection rules, relative to the project root. Every entry must exist for the directory to match. |
variables |
object[] | no | Values the user fills in before a build. Each entry has name (string, required, unique), label (string, falls back to name), required (bool), default (string or null). |
build.steps |
array | yes (non-empty) | Commands run in order on the target. Each entry is either a plain command string or { "id": "...", "run": "..." }. |
build.artifactPath |
string | no | Single default artifact path. Used when build.artifacts is empty. |
build.artifacts |
string[] | no | Artifact list; wins over artifactPath when non-empty. |
cache.paths |
string[] | no | Remote directories kept across builds. They take part in the push exclude set (see below). |
A complete example, annotated below:
{
"displayName": "Xcode (iOS)",
"platform": "xcode",
"include": { "paths": ["*.xcodeproj"] },
"variables": [
{ "name": "scheme", "label": "Xcode Scheme", "required": true },
{ "name": "configuration", "label": "Build Configuration", "required": false, "default": "Release" },
{ "name": "sdk", "label": "SDK", "required": false, "default": "iphoneos" }
],
"build": {
"steps": [
{
"id": "build",
"run": "xcodebuild -scheme {{scheme}} -configuration {{configuration}} -sdk {{sdk}} -derivedDataPath .cgw/derived-data {{signingExtraArgs}} build"
}
],
"artifactPath": ".cgw/derived-data/Build/Products/{{configuration}}-{{sdk}}/{{scheme}}.app"
},
"cache": { "paths": [".cgw/", "Pods/"] }
}Annotations:
-
displayNameis what the WebUI shows on the card;platformis only a badge. -
include.pathsholds one rule, a last-segment wildcard: any*.xcodeprojat the project root. - The three
variablesare filled in per task;schemeis required, the other two fall back to their defaults. - The single step is named
build, so the build log can name it on failure. -
{{signingExtraArgs}}is not declared invariables— it is the one reserved placeholder (see below). -
artifactPathis a path template: the same{{...}}substitution applies, but no shell quoting. -
cache.pathsnames the directories that must survive between builds.
Every entry in include.paths must exist for a directory to match that build type — the rules are ANDed, not ORed. A manifest with an empty include.paths never matches anything.
A rule with no * is a plain existence check on the joined path (gradlew, composeApp/src/iosMain). A rule may use * in its last segment (*.xcodeproj, iosApp/*.xcodeproj); the parent directory is listed and its entries are wildcard-matched. A leading ./ is ignored.
Detection is offered by all three front ends, always against a host directory (the machine the daemon runs on):
- WebUI: the build-type page has a path box plus a search button.
- CLI:
cgw manifests detect /path/to/project- MCP: the
cgw_detect_manifeststool.
The daemon returns every match, not one winner — when several types hit, the user picks. Detection only sees directories inside the allowed host roots: a path outside them is rejected with 403 outsideRoot, a path that is not a directory with 400 sourceNotFound. Manifests that fail to parse are skipped.
Variables are the values a task supplies to a build. Each is declared as { "name", "label", "required", "default" }; names must be unique per manifest, and the empty name is rejected.
-
Substitution:
{{name}}in a step command or in an artifact path is replaced by the variable's value. An undeclared placeholder is left verbatim by the renderer, but saving or loading such a manifest is rejected — every placeholder must be a declared variable, exceptsigningExtraArgs. -
Resolution order: the value given by the task, else the declared
default, else empty. Values are trimmed; an empty provided value falls back to the default. -
Required: a
requiredvariable that ends up empty fails the build with400 variableRequired, and the error names the variable. -
Shell quoting: in step commands a substituted value is shell-quoted before it reaches the shell — values made only of letters, digits and
/ . _ - ~ + : = ,pass through, anything else is wrapped in single quotes with embedded quotes escaped. A scheme namedMy App; rm -rf /becomes one argument, not two commands. Artifact paths are not shell-quoted: they are paths, not commands.
signingExtraArgs is a built-in placeholder and must not be declared in variables (declaring it is a validation error). It is injected from the task's signingMode and expands to several bare arguments, so it is deliberately never quoted as a single value:
signingMode |
expansion |
|---|---|
signed |
empty (nothing is added) |
unsigned |
CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY= |
Any value other than signed (case-insensitive) is treated as unsigned.
Two forms are accepted for each step:
"steps": [
"flutter pub get",
{ "id": "pods", "run": "cd ios && pod install" }
]- A plain command string — the original shape.
- A named step
{ "id": "...", "run": "...", "outputs": { ... } }. Theidmust be non-empty and unique within the manifest.-
Diagnostic display: On a build failure the remote prints a bare tool error, so the daemon first writes a line listing the steps (
id(1) -> id(2) -> ...) whenever any step is named, identifying the failing step precisely. -
Step-level output declaration (
outputs): Named steps can declare outputs produced by that step, supporting key-value mappings or an array of objects (optional fields includepath,description,requireddefaulting to true,directorydefaulting to false). Upon successful build completion, the daemon verifies their existence and directory/file types. For batch workflows, these outputs are registered intojob.producedfor downstream steps to consume via{{steps.<stepId>.outputs.<name>}}.
-
Diagnostic display: On a build failure the remote prints a bare tool error, so the daemon first writes a line listing the steps (
- Commands must be non-empty; an empty command is a validation error.
- The steps run in order, joined by
&&into one remote command:cd <remotePath> && step1 && step2 && .... The first non-zero exit stops the build, and the whole run is one SSH exec.
An artifact is what the build is supposed to produce. Both fields are templates and are rendered with the task's variables (no shell quoting):
task.artifacts > task.artifactPath > manifest.build.artifacts > manifest.build.artifactPath
- Inside one level, a non-empty list wins over the single path; blanks are dropped.
- A task can override the manifest per task: a non-empty task
artifactslist wins, then a taskartifactPath, and only then the manifest's own list, then its single path. - A relative path is resolved against the remote project directory; a path starting with
/or~is used as-is. - After a successful build the daemon reconnects and checks each artifact on the target, then reports size and names anything missing in the job message.
- Artifacts are also what the daemon reports in a job: the job record carries
artifactPath(the first artifact) and the fullartifactslist.
Build types declare the remote directories that should survive between builds, for example .gradle/, ios/Pods/ or .cgw/.
These paths join the exclude set used by a push, so the local copy of a cache directory never overwrites the remote one. A push excludes, in order:
- the project's own excludes, which default to
.git,.DS_StoreandThumbs.db; - the fixed host-local artifact blacklist (things like
DerivedData,.cgw,build,.gradle,node_modules,.dart_tool,Pods,target— these are never pushed); -
cache.pathsfrom every manifest the project uses.
An exclude entry matches by name at any depth (.git also matches sub/.git), or by relative-path prefix when the entry contains / (ios/Pods/ covers everything below it).
The CLI covers the whole surface:
cgw manifests # list (same as `manifests list`)
cgw manifests status # where the directory is, how many, which are invalid, which templates are missing
cgw manifests show <id> # print the raw JSON
cgw manifests save <id> --file <path> # or --file - to read stdin; an existing id needs --force
cgw manifests rm <id>
cgw manifests templates # which shipped templates are missing
cgw manifests reset [id...] # write back ONLY missing template files
cgw manifests refresh # re-read the directory and report added / changed / removed
cgw manifests detect <host dir>
cgw manifests import <file.json> [--id <name>] [--force]
cgw manifests export <id> [--save <path>] # without --save it prints to stdout
cgw manifests schema # same as `cgw schema manifest`Notes:
-
resetonly writes files that do not exist. It never touches a manifest you edited; to get a pristine template back, delete it first and then reset. -
importandsaverefuse to overwrite an existing id unless--forceis given, so a script cannot clobber your build type silently. -
refreshdiffs against the state seen earlier in this run (a baseline is taken at startup), so the first refresh does not report all four templates as new. Deleting the whole directory and refreshing recreates it and re-seeds the templates. - The WebUI build-type page offers the same work: a toolbar with refresh, "restore missing templates" (only shown when something is missing) and new; a detect box with a run button; and per card, edit the raw JSON, export the file, and delete. Because the browser cannot read a file the user picks, "new" asks only for an id and writes a starter manifest — use
cgw manifests importto bring in a file from disk. - Manifest ids are restricted to letters, digits,
-and_; the save API rejects anything else. Saving a manifest that fails validation returns a400with the full list of validation messages.
Every build type must satisfy a JSON Schema that is generated from the Rust struct — it cannot drift from the implementation:
cgw schema manifestThe same schema is available as the MCP resource cgw://schema/manifest and over HTTP as GET /api/schema/manifest. It is a draft-07 schema that states exactly what the code enforces: displayName and build are required, build.steps needs at least one item, variables[].name is non-empty, default is a nullable string, and steps is an anyOf of the two accepted step shapes.
Taken verbatim from src-tauri/templates/xcode.json, with a named step:
{
"displayName": "Xcode (iOS)",
"platform": "xcode",
"include": { "paths": ["*.xcodeproj"] },
"variables": [
{ "name": "scheme", "label": "Xcode Scheme", "required": true },
{ "name": "configuration", "label": "Build Configuration", "required": false, "default": "Release" },
{ "name": "sdk", "label": "SDK", "required": false, "default": "iphoneos" }
],
"build": {
"steps": [
{
"id": "build",
"run": "xcodebuild -scheme {{scheme}} -configuration {{configuration}} -sdk {{sdk}} -derivedDataPath .cgw/derived-data {{signingExtraArgs}} build"
}
],
"artifactPath": ".cgw/derived-data/Build/Products/{{configuration}}-{{sdk}}/{{scheme}}.app"
},
"cache": { "paths": [".cgw/", "Pods/"] }
}Two unnamed steps, no variables, no cache:
{
"displayName": "Make project",
"platform": "make",
"include": { "paths": ["Makefile"] },
"build": {
"steps": ["make clean", "make all"],
"artifactPath": "build/app.bin"
}
}Save it with cgw manifests save make --file make.json, and it is immediately selectable on a build task. Build types are used by tasks; see Tasks for manifest, variables, signingMode and the per-task artifact override, and CLI for the full command reference.
← Home