@cloud-cli/on 1.34.2 → 1.35.0

package/dist/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAmCA,wBAAgB,cAAc,CAAC,KAAK,UAAQ,GAAG,MAAM,CAmBpD"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AA6CA,wBAAgB,cAAc,CAAC,KAAK,UAAQ,GAAG,MAAM,CA+CpD"}

package/dist/on.js

@@ -5549,9 +5549,29 @@ W.use = Li, W.walkTokens = function(e, t) {
 }, W.parseInline = Ii.parseInline, W.Parser = Pi, W.parser = Pi.parse, W.Renderer = Mi, W.TextRenderer = Ni, W.Lexer = ji, W.lexer = ji.lex, W.Tokenizer = Ai, W.Hooks = Fi, W.parse = W, W.options, W.setOptions, W.walkTokens, W.parseInline, Pi.parse, ji.lex;
 //#endregion
 //#region docs/workflow-syntax.md?raw
-var Ri = "# Workflow Documentation\n\nThis is the living documentation for workflow authors. It is organized using the four Diataxis modes:\n\n- **Tutorials** teach the shortest path to a working workflow.\n- **How-to guides** solve focused tasks.\n- **Reference** documents the accepted syntax.\n- **Explanation** describes execution and security decisions.\n\n## Tutorials\n\n### Your First Workflow\n\nCreate a draft in the authenticated workflow editor, or send the YAML to the API:\n\n```yaml\nname: Hello\n\non:\n  generic: {}\n\nsteps:\n  - id: greet\n    name: Greet\n    run: echo \"Hello ${inputs.name}\"\n```\n\nSave it, validate it, and publish it. Only published and enabled workflows receive webhook or scheduled events.\n\nThe `generic` provider accepts a JSON request body as `inputs`. For example:\n\n```bash\ncurl -X POST http://localhost:11235/webhooks/generic \\\n  -H 'content-type: application/json' \\\n  --data '{\"name\":\"Ada\"}'\n```\n\n### Build a GitHub Workflow\n\n```yaml\nname: Build\n\non:\n  github:\n    events: [push]\n    owner: cloud-cli\n    repo: on\n    branches: [main]\n\nsteps:\n  - id: checkout\n    name: Checkout\n    env:\n      clone_url: ${inputs.clone_url}\n      commit_sha: ${inputs.commit_sha}\n    run: |\n      git clone --depth 1 \"$clone_url\" .\n      git checkout \"$commit_sha\"\n\n  - id: test\n    name: Test\n    run: pnpm install && pnpm test\n```\n\nGitHub webhooks must be signed with the configured `GITHUB_WEBHOOK_SECRET`. The preprocessor exposes normalized inputs including `event`, `owner`, `repo`, `branch`, `tag`, `ref`, `full_name`, `clone_url`, `commit_sha`, `author`, `action`, `changes`, and the original `raw` body.\n\n## How-To Guides\n\n### Reference Another Environment Value\n\nEnvironment entries are evaluated from top to bottom. Earlier values are available through `env` to later values:\n\n```yaml\nenv:\n  image: ${inputs.repo}\n  image_tag: ${env.image}:latest\n  artifact_name: ${env.image_tag}-${inputs.commit_sha}\n```\n\nWorkflow-level values are available to every step. Step-level `env` values are evaluated after workflow-level values and can override them for that step.\n\nUse `${inputs.name}`, `${env.NAME}`, `${secrets.NAME}`, and `${steps.step_id.outputs.value}` where the value is available. A value without `${...}` remains literal text.\n\n### Run a Container with a Host Volume\n\nUse `image` with `volumes`. A volume is passed directly to `docker run` as a `-v` mapping:\n\n```yaml\nsteps:\n  - id: sign\n    name: Sign release\n    image: alpine:latest\n    volumes:\n      - /var/lib/runner/secrets-store:/secrets:ro\n    run: |\n      ./sign.sh /secrets/signing.key dist/release.tar.gz\n```\n\nThe source path is on the worker host. The destination path is inside the container. Use absolute host paths when a specific host directory is required. The workflow must be trusted because volume mappings can expose host data to a container.\n\nA single string is also accepted:\n\n```yaml\nvolumes: /var/lib/runner/secrets-store:/secrets:ro\n```\n\n### Pass Additional Docker Arguments\n\nUse `dockerArgs` for additional arguments to `docker run`, before the image name:\n\n```yaml\nsteps:\n  - id: build\n    image: docker:cli\n    dockerArgs:\n      - --network=host\n      - --user=1000:1000\n    run: docker build -t example:latest .\n```\n\nArguments are not interpreted or shell-expanded by the runner. They are passed as individual Docker CLI arguments.\n\n### Use a Matrix\n\nKeep the matrix in the workflow definition:\n\n```yaml\nname: Package\n\nmatrix:\n  node: [18, 20]\n  os: [ubuntu, alpine]\n\non:\n  generic: {}\n\nenv:\n  node_version: ${env.MATRIX_NODE}\n\nsteps:\n  - id: package\n    image: node:${env.MATRIX_NODE}\n    run: npm pack\n```\n\nThe runner creates one job for every Cartesian combination. The example creates four jobs. Each variant receives `MATRIX_NODE` and `MATRIX_OS` environment variables.\n\n### Add a Scheduled Trigger\n\n```yaml\non:\n  schedule:\n    - id: nightly\n      cron: '0 2 * * *'\n      timezone: Europe/Berlin\n```\n\nCron expressions have five fields: minute, hour, day of month, month, and day of week. The scheduler uses the declared IANA timezone.\n\nSolar triggers use `sunrise` or `sunset` and geographic coordinates:\n\n```yaml\non:\n  solar:\n    - id: morning\n      event: sunrise\n      latitude: 52.52\n      longitude: 13.405\n      offset: +15m\n```\n\n### Use Secrets\n\nCreate a secret in the management UI or with the API, then reference it in environment values:\n\n```yaml\nsteps:\n  - id: publish\n    env:\n      npm_token: ${secrets.NPM_TOKEN}\n    run: npm publish\n```\n\nSecret values are delivered to a worker after it claims the job. Do not write them into reports or artifacts.\n\n### Persist Artifacts and Caches\n\nArtifacts are captured from the workspace after a successful run:\n\n```yaml\nartifacts:\n  paths:\n    - dist\n    - reports/**/*.json\n```\n\nCaches are restored before steps start and replaced after a successful run:\n\n```yaml\ncache:\n  key: npm-${inputs.repo}-${inputs.branch}\n  paths:\n    - node_modules\n```\n\nConfigure a shared FileBin backend on the server and workers with `RUNNER_FILE_API_URL`, `RUNNER_FILE_BIN`, and optionally `RUNNER_FILE_PASSWORD`. Without it, the runner uses the database fallback. Cache keys are scoped by workflow; artifacts are scoped by job.\n\nPopulate workspace files from managed secrets before steps run:\n\n```yaml\nsecretFiles:\n  .config/signing.key: SIGNING_KEY\n```\n\nSecret files are created with owner-only permissions and are removed with the job workspace.\n\n## Reference\n\n### Top-Level Workflow Fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `name` | string | Required human-readable workflow name shown in the UI and reports. |\n| `id` | string | Optional identifier used when deriving an ID outside the management API. The management API ID is authoritative after creation. |\n| `on` | object | Required trigger configuration. |\n| `env` | object | Workflow environment values, evaluated in declaration order. |\n| `matrix` | object | Matrix dimensions. Each value is an array of strings, numbers, or booleans. |\n| `concurrency` | object | Optional concurrency group and cancellation policy. |\n| `tags` | string[] | Worker capability tags required by the job. |\n| `artifacts` | object | Workspace paths captured after successful runs. |\n| `cache` | object | Keyed workspace paths restored before and saved after successful runs. |\n| `secretFiles` | object | Workspace-relative file paths mapped to secret names. |\n| `steps` | object[] | Required non-empty ordered list of steps. |\n| `retries` | integer | Additional attempts for a failed step. Must be zero or greater. |\n\n`includes` and workflow-to-workflow imports are not supported. Workflow definitions are stored as complete database revisions. Reusable behavior should be implemented through the planned step reuse mechanism rather than filesystem imports.\n\n### Triggers\n\nThe first non-`schedule`/`solar` key in `on` is the provider trigger. Supported providers include `generic` and `github`.\n\n#### GitHub Trigger Filters\n\n| Field | Type | Behavior |\n| --- | --- | --- |\n| `events` | string[] | Exact event names such as `push` or `pull_request`. |\n| `owner` | string or string[] | Exact repository owner. |\n| `repo` | string or string[] | Exact repository name. |\n| `name` | string or string[] | Exact `owner/repo` name. |\n| `branches` | string or string[] | Glob patterns matching normalized branches or tags. |\n| `refs` | string or string[] | Alias for branch/ref matching. |\n| `tag` | boolean | Requires a tag push when true, a non-tag event when false. |\n| `tags` | string[] | Regular expressions matched against the tag value. |\n| `paths` | string[] | Glob patterns matched against changed files. |\n| `if` | string or string[] | Safe JavaScript condition evaluated after provider filters. |\n\nConfigured fields are combined with AND. Multiple values within a field are combined with OR. Negated `!value` entries are supported by exact-value filters.\n\n#### Schedule Trigger\n\n```yaml\nschedule:\n  - id: hourly\n    cron: '0 * * * *'\n    timezone: UTC\n```\n\n#### Solar Trigger\n\n```yaml\nsolar:\n  - id: sunrise-build\n    event: sunrise\n    latitude: 52.52\n    longitude: 13.405\n    timezone: Europe/Berlin\n    offset: -15m\n```\n\n### Environment and Expressions\n\nInterpolated strings use standard JavaScript template expressions inside `${...}`. The safe evaluator supports literals, property access, arithmetic, comparisons, boolean operators, ternaries, arrays, objects, and these helpers:\n\n```text\nString(value)\nNumber(value)\nBoolean(value)\nJSON.parse(value)\nJSON.stringify(value)\nObject.keys(value)\n```\n\nAvailable context objects are:\n\n| Object | Available data |\n| --- | --- |\n| `inputs` | Trigger payload and normalized provider inputs. |\n| `env` | Runner environment plus earlier workflow or step environment entries. |\n| `secrets` | Decrypted job-scoped secrets. |\n| `steps` | Earlier step statuses, exit codes, and outputs. |\n| `files` | Workspace-scoped `exists`, `readFile`, and `join` helpers for `eval:` steps. |\n\nExpressions cannot access JavaScript constructors or prototypes. Shell commands are not expression-evaluated; only declared interpolation fields are evaluated.\n\n### Steps\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `id` | string | Stable identifier used by `steps.<id>`. |\n| `name` | string | Display name. Defaults to `id`. |\n| `run` | string | Shell command or script. Mutually exclusive with `eval`. |\n| `eval` | string | In-process safe expression. Mutually exclusive with `run`. |\n| `env` | object | Step environment, evaluated after workflow environment. |\n| `image` | string | Docker image. Selects container execution for the step. |\n| `volumes` | string or string[] | Docker `-v` mappings. |\n| `dockerArgs` | string[] | Additional raw arguments for `docker run`. |\n| `timeoutMs` | positive integer | Maximum step runtime. Defaults to 30 seconds. |\n| `if` | string | Safe condition. False conditions produce a skipped step. |\n\n`run` steps execute through the selected worker driver. With `image`, the command runs as `sh -c` inside Docker. Without `image`, it runs through the worker shell. `eval` steps run inside the worker process and can produce structured outputs for later steps.\n\n### Management and API\n\nWorkflow definitions are drafted, validated, published, enabled, and deleted through the authenticated management UI or these endpoints:\n\n```text\nPOST /api/workflows/validate\nGET  /api/workflows\nGET  /api/workflows/:id\nPUT  /api/workflows/:id\nPOST /api/workflows/:id/publish\nDELETE /api/workflows/:id\n```\n\nOnly published workflows with `enabled: true` are matched for incoming triggers. Saving a workflow creates a new immutable revision. Existing jobs continue to use the revision recorded when they were created.\n\n## Explanation\n\n### Why Workflow YAML Lives in the Database\n\nThe server stores source YAML and normalized revisions in the database. Workers are stateless: they fetch the referenced revision when claiming a job and do not read workflow files from their local filesystem. This keeps every worker on the same definition and makes published revisions reproducible.\n\n### Why Matrix Expansion Happens at Trigger Time\n\nThe stored revision remains one canonical workflow. When a trigger matches, the server creates one queue job per matrix combination. The payload records the matrix context, and the worker resolves that same variant before execution. This avoids storing duplicate workflow revisions while keeping each job independently observable.\n\n### Docker Volumes and Trust\n\n`volumes` and `dockerArgs` are intentionally powerful options. A host volume can expose credentials or signing material, and Docker arguments can change networking, users, capabilities, or isolation. Only trusted administrators should publish workflows using these fields. The runner does not copy, inspect, or redact files mounted into containers.\n\n### Reuse and Imports\n\nFilesystem imports were removed because workers no longer load workflow files. Future step reuse should operate on database-owned definitions or explicit reusable step mechanisms, keeping revisioning and authorization visible to the control plane.\n", zi = "\n  <svg aria-hidden=\"true\" viewBox=\"0 0 24 24\" width=\"16\" height=\"16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.8\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n    <circle cx=\"12\" cy=\"12\" r=\"9\"></circle>\n    <path d=\"M9.6 9a2.5 2.5 0 1 1 4.2 1.8c-1.2 1-1.8 1.4-1.8 2.7\"></path>\n    <path d=\"M12 17h.01\"></path>\n  </svg>", Bi = "\n  :root { color-scheme: dark; }\n  * { box-sizing: border-box; }\n  body { margin: 0; background: #030712; color: #e5e7eb; font-family: ui-sans-serif, system-ui, sans-serif; }\n  main { max-width: 78rem; margin: 0 auto; padding: 2rem 1rem 5rem; }\n  article { max-width: 54rem; margin: 0 auto; line-height: 1.7; }\n  h1, h2, h3 { color: #f9fafb; line-height: 1.2; letter-spacing: -0.02em; }\n  h1 { font-size: 2.25rem; margin: 0 0 1rem; }\n  h2 { border-top: 1px solid #1f2937; margin-top: 3rem; padding-top: 1.5rem; font-size: 1.6rem; }\n  h3 { margin-top: 2rem; font-size: 1.15rem; }\n  p, li { color: #cbd5e1; }\n  a { color: #93c5fd; }\n  code { border-radius: .35rem; background: #111827; color: #bfdbfe; padding: .12rem .35rem; font-size: .9em; }\n  pre { overflow-x: auto; border: 1px solid #1f2937; border-radius: .75rem; background: #0b1120; padding: 1rem; }\n  pre code { background: transparent; padding: 0; color: #d1d5db; }\n  table { width: 100%; border-collapse: collapse; display: block; overflow-x: auto; margin: 1rem 0; }\n  th, td { border-bottom: 1px solid #1f2937; padding: .65rem .75rem; text-align: left; vertical-align: top; }\n  th { color: #f9fafb; background: #111827; }\n  blockquote { border-left: 3px solid #6366f1; margin-left: 0; padding-left: 1rem; color: #94a3b8; }\n  .topbar { display: flex; justify-content: space-between; gap: 1rem; align-items: center; max-width: 78rem; margin: 0 auto; padding: 1rem; }\n  .back { display: inline-flex; align-items: center; gap: .45rem; color: #94a3b8; text-decoration: none; font-size: .85rem; }\n  .back:hover, .back:focus-visible { color: #f9fafb; }\n  @media (min-width: 640px) { main { padding: 3rem 1.5rem 6rem; } }\n";
+var Ri = "# Workflow Documentation\n\nThis is the living documentation for workflow authors. It is organized using the four Diataxis modes:\n\n- **Tutorials** teach the shortest path to a working workflow.\n- **How-to guides** solve focused tasks.\n- **Reference** documents the accepted syntax.\n- **Explanation** describes execution and security decisions.\n\n## Tutorials\n\n### Your First Workflow\n\nCreate a draft in the authenticated workflow editor, or send the YAML to the API:\n\n```yaml\nname: Hello\n\non:\n  generic: {}\n\nsteps:\n  - id: greet\n    name: Greet\n    run: echo \"Hello ${inputs.name}\"\n```\n\nSave it, validate it, and publish it. Only published and enabled workflows receive webhook or scheduled events.\n\nThe `generic` provider accepts a JSON request body as `inputs`. For example:\n\n```bash\ncurl -X POST http://localhost:11235/webhooks/generic \\\n  -H 'content-type: application/json' \\\n  --data '{\"name\":\"Ada\"}'\n```\n\n### Build a GitHub Workflow\n\n```yaml\nname: Build\n\non:\n  github:\n    events: [push]\n    owner: cloud-cli\n    repo: on\n    branches: [main]\n\nsteps:\n  - id: checkout\n    name: Checkout\n    env:\n      clone_url: ${inputs.clone_url}\n      commit_sha: ${inputs.commit_sha}\n    run: |\n      git clone --depth 1 \"$clone_url\" .\n      git checkout \"$commit_sha\"\n\n  - id: test\n    name: Test\n    run: pnpm install && pnpm test\n```\n\nGitHub webhooks must be signed with the configured `GITHUB_WEBHOOK_SECRET`. The preprocessor exposes normalized inputs including `event`, `owner`, `repo`, `branch`, `tag`, `ref`, `full_name`, `clone_url`, `commit_sha`, `author`, `action`, `changes`, and the original `raw` body.\n\n## How-To Guides\n\n### Reference Another Environment Value\n\nEnvironment entries are evaluated from top to bottom. Earlier values are available through `env` to later values:\n\n```yaml\nenv:\n  image: ${inputs.repo}\n  image_tag: ${env.image}:latest\n  artifact_name: ${env.image_tag}-${inputs.commit_sha}\n```\n\nWorkflow-level values are available to every step. Step-level `env` values are evaluated after workflow-level values and can override them for that step.\n\nUse `${inputs.name}`, `${env.NAME}`, `${secrets.NAME}`, and `${steps.step_id.outputs.value}` where the value is available. A value without `${...}` remains literal text.\n\n### Run a Container with a Host Volume\n\nUse `image` with `volumes`. A volume is passed directly to `docker run` as a `-v` mapping:\n\n```yaml\nsteps:\n  - id: sign\n    name: Sign release\n    image: alpine:latest\n    volumes:\n      - /var/lib/runner/secrets-store:/secrets:ro\n    run: |\n      ./sign.sh /secrets/signing.key dist/release.tar.gz\n```\n\nThe source path is on the worker host. The destination path is inside the container. Use absolute host paths when a specific host directory is required. The workflow must be trusted because volume mappings can expose host data to a container.\n\nA single string is also accepted:\n\n```yaml\nvolumes: /var/lib/runner/secrets-store:/secrets:ro\n```\n\n### Pass Additional Docker Arguments\n\nUse `dockerArgs` for additional arguments to `docker run`, before the image name:\n\n```yaml\nsteps:\n  - id: build\n    image: docker:cli\n    dockerArgs:\n      - --network=host\n      - --user=1000:1000\n    run: docker build -t example:latest .\n```\n\nArguments are not interpreted or shell-expanded by the runner. They are passed as individual Docker CLI arguments.\n\n### Use a Matrix\n\nKeep the matrix in the workflow definition:\n\n```yaml\nname: Package\n\nmatrix:\n  node: [18, 20]\n  os: [ubuntu, alpine]\n\non:\n  generic: {}\n\nenv:\n  node_version: ${env.MATRIX_NODE}\n\nsteps:\n  - id: package\n    image: node:${env.MATRIX_NODE}\n    run: npm pack\n```\n\nThe runner creates one job for every Cartesian combination. The example creates four jobs. Each variant receives `MATRIX_NODE` and `MATRIX_OS` environment variables.\n\n### Add a Scheduled Trigger\n\n```yaml\non:\n  schedule:\n    - id: nightly\n      cron: '0 2 * * *'\n      timezone: Europe/Berlin\n```\n\nCron expressions have five fields: minute, hour, day of month, month, and day of week. The scheduler uses the declared IANA timezone.\n\nSolar triggers use `sunrise` or `sunset` and geographic coordinates:\n\n```yaml\non:\n  solar:\n    - id: morning\n      event: sunrise\n      latitude: 52.52\n      longitude: 13.405\n      offset: +15m\n```\n\n### Use Secrets\n\nCreate a secret in the management UI or with the API, then reference it in environment values:\n\n```yaml\nsteps:\n  - id: publish\n    env:\n      npm_token: ${secrets.NPM_TOKEN}\n    run: npm publish\n```\n\nSecret values are delivered to a worker after it claims the job. Do not write them into reports or artifacts.\n\n### Persist Artifacts and Caches\n\nArtifacts are captured from the workspace after a successful run:\n\n```yaml\nartifacts:\n  paths:\n    - dist\n    - reports/**/*.json\n```\n\nCaches are restored before steps start and saved after a successful run:\n\n```yaml\ncache:\n  key: npm-${inputs.repo}-${inputs.branch}\n  paths:\n    - node_modules\n```\n\nConfigure a shared FileBin backend on the server and workers with `RUNNER_FILE_API_URL`, `RUNNER_FILE_BIN`, and optionally `RUNNER_FILE_PASSWORD`. Create a bin with `POST /bin`, then configure its ID. Without FileBin configuration, the runner uses the central database fallback. Cache keys are scoped by workflow; artifacts are scoped by job. Stored collections are limited to 50 MiB per capture.\n\nAdministrators can download a captured artifact with `GET /api/runs/:jobId/artifacts/:path`.\n\nPopulate workspace files from managed secrets before steps run:\n\n```yaml\nsecretFiles:\n  .config/signing.key: SIGNING_KEY\n```\n\nSecret files are created with owner-only permissions in the worker workspace. They must be handled according to the worker storage lifecycle and should not be included in artifacts or caches.\n\n## Reference\n\n### Top-Level Workflow Fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `name` | string | Required human-readable workflow name shown in the UI and reports. |\n| `id` | string | Optional identifier used when deriving an ID outside the management API. The management API ID is authoritative after creation. |\n| `on` | object | Required trigger configuration. |\n| `env` | object | Workflow environment values, evaluated in declaration order. |\n| `matrix` | object | Matrix dimensions. Each value is an array of strings, numbers, or booleans. |\n| `concurrency` | object | Optional concurrency group and cancellation policy. |\n| `tags` | string[] | Worker capability tags required by the job. |\n| `artifacts` | object | Workspace paths captured after successful runs. |\n| `cache` | object | Keyed workspace paths restored before and saved after successful runs. |\n| `secretFiles` | object | Workspace-relative file paths mapped to secret names. |\n| `steps` | object[] | Required non-empty ordered list of steps. |\n| `retries` | integer | Additional attempts for a failed step. Must be zero or greater. |\n\n`includes` and workflow-to-workflow imports are not supported. Workflow definitions are stored as complete database revisions. Reusable behavior should be implemented through the planned step reuse mechanism rather than filesystem imports.\n\n### Triggers\n\nThe first non-`schedule`/`solar` key in `on` is the provider trigger. Supported providers include `generic` and `github`.\n\n#### GitHub Trigger Filters\n\n| Field | Type | Behavior |\n| --- | --- | --- |\n| `events` | string[] | Exact event names such as `push` or `pull_request`. |\n| `owner` | string or string[] | Exact repository owner. |\n| `repo` | string or string[] | Exact repository name. |\n| `name` | string or string[] | Exact `owner/repo` name. |\n| `branches` | string or string[] | Glob patterns matching normalized branches or tags. |\n| `refs` | string or string[] | Alias for branch/ref matching. |\n| `tag` | boolean | Requires a tag push when true, a non-tag event when false. |\n| `tags` | string[] | Regular expressions matched against the tag value. |\n| `paths` | string[] | Glob patterns matched against changed files. |\n| `if` | string or string[] | Safe JavaScript condition evaluated after provider filters. |\n\nConfigured fields are combined with AND. Multiple values within a field are combined with OR. Negated `!value` entries are supported by exact-value filters.\n\n#### Schedule Trigger\n\n```yaml\nschedule:\n  - id: hourly\n    cron: '0 * * * *'\n    timezone: UTC\n```\n\n#### Solar Trigger\n\n```yaml\nsolar:\n  - id: sunrise-build\n    event: sunrise\n    latitude: 52.52\n    longitude: 13.405\n    timezone: Europe/Berlin\n    offset: -15m\n```\n\n### Environment and Expressions\n\nInterpolated strings use standard JavaScript template expressions inside `${...}`. The safe evaluator supports literals, property access, arithmetic, comparisons, boolean operators, ternaries, arrays, objects, and these helpers:\n\n```text\nString(value)\nNumber(value)\nBoolean(value)\nJSON.parse(value)\nJSON.stringify(value)\nObject.keys(value)\n```\n\nAvailable context objects are:\n\n| Object | Available data |\n| --- | --- |\n| `inputs` | Trigger payload and normalized provider inputs. |\n| `env` | Runner environment plus earlier workflow or step environment entries. |\n| `secrets` | Decrypted job-scoped secrets. |\n| `steps` | Earlier step statuses, exit codes, and outputs. |\n| `files` | Workspace-scoped `exists`, `readFile`, and `join` helpers for `eval:` steps. |\n\nExpressions cannot access JavaScript constructors or prototypes. Shell commands are not expression-evaluated; only declared interpolation fields are evaluated.\n\n### Steps\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `id` | string | Stable identifier used by `steps.<id>`. |\n| `name` | string | Display name. Defaults to `id`. |\n| `run` | string | Shell command or script. Mutually exclusive with `eval`. |\n| `eval` | string | In-process safe expression. Mutually exclusive with `run`. |\n| `env` | object | Step environment, evaluated after workflow environment. |\n| `image` | string | Docker image. Selects container execution for the step. |\n| `volumes` | string or string[] | Docker `-v` mappings. |\n| `dockerArgs` | string[] | Additional raw arguments for `docker run`. |\n| `timeoutMs` | positive integer | Maximum step runtime. Defaults to 30 seconds. |\n| `if` | string | Safe condition. False conditions produce a skipped step. |\n\n`run` steps execute through the selected worker driver. With `image`, the command runs as `sh -c` inside Docker. Without `image`, it runs through the worker shell. `eval` steps run inside the worker process and can produce structured outputs for later steps.\n\n### Management and API\n\nWorkflow definitions are drafted, validated, published, enabled, and deleted through the authenticated management UI or these endpoints:\n\n```text\nPOST /api/workflows/validate\nGET  /api/workflows\nGET  /api/workflows/:id\nPUT  /api/workflows/:id\nPOST /api/workflows/:id/publish\nDELETE /api/workflows/:id\n```\n\nOnly published workflows with `enabled: true` are matched for incoming triggers. Saving a workflow creates a new immutable revision. Existing jobs continue to use the revision recorded when they were created.\n\n## Explanation\n\n### Why Workflow YAML Lives in the Database\n\nThe server stores source YAML and normalized revisions in the database. Workers are stateless: they fetch the referenced revision when claiming a job and do not read workflow files from their local filesystem. This keeps every worker on the same definition and makes published revisions reproducible.\n\n### Why Matrix Expansion Happens at Trigger Time\n\nThe stored revision remains one canonical workflow. When a trigger matches, the server creates one queue job per matrix combination. The payload records the matrix context, and the worker resolves that same variant before execution. This avoids storing duplicate workflow revisions while keeping each job independently observable.\n\n### Docker Volumes and Trust\n\n`volumes` and `dockerArgs` are intentionally powerful options. A host volume can expose credentials or signing material, and Docker arguments can change networking, users, capabilities, or isolation. Only trusted administrators should publish workflows using these fields. The runner does not copy, inspect, or redact files mounted into containers.\n\n### Reuse and Imports\n\nFilesystem imports were removed because workers no longer load workflow files. Future step reuse should operate on database-owned definitions or explicit reusable step mechanisms, keeping revisioning and authorization visible to the control plane.\n", zi = "\n  <svg aria-hidden=\"true\" viewBox=\"0 0 24 24\" width=\"16\" height=\"16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.8\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n    <circle cx=\"12\" cy=\"12\" r=\"9\"></circle>\n    <path d=\"M9.6 9a2.5 2.5 0 1 1 4.2 1.8c-1.2 1-1.8 1.4-1.8 2.7\"></path>\n    <path d=\"M12 17h.01\"></path>\n  </svg>", Bi = "\n  :root { color-scheme: dark; }\n  * { box-sizing: border-box; }\n  body { margin: 0; background: #030712; color: #e5e7eb; font-family: ui-sans-serif, system-ui, sans-serif; }\n  main { max-width: 78rem; margin: 0 auto; padding: 2rem 1rem 5rem; }\n  article { max-width: 54rem; margin: 0 auto; line-height: 1.7; }\n  h1, h2, h3 { color: #f9fafb; line-height: 1.2; letter-spacing: -0.02em; }\n  h1 { font-size: 2.25rem; margin: 0 0 1rem; }\n  h2 { border-top: 1px solid #1f2937; margin-top: 3rem; padding-top: 1.5rem; font-size: 1.6rem; }\n  h3 { margin-top: 2rem; font-size: 1.15rem; }\n  p, li { color: #cbd5e1; }\n  a { color: #93c5fd; }\n  code { border-radius: .35rem; background: #111827; color: #bfdbfe; padding: .12rem .35rem; font-size: .9em; }\n  pre { overflow-x: auto; border: 1px solid #1f2937; border-radius: .75rem; background: #0b1120; padding: 1rem; }\n  pre code { background: transparent; padding: 0; color: #d1d5db; }\n  table { width: 100%; border-collapse: collapse; display: block; overflow-x: auto; margin: 1rem 0; }\n  th, td { border-bottom: 1px solid #1f2937; padding: .65rem .75rem; text-align: left; vertical-align: top; }\n  th { color: #f9fafb; background: #111827; }\n  blockquote { border-left: 3px solid #6366f1; margin-left: 0; padding-left: 1rem; color: #94a3b8; }\n  .topbar { display: flex; justify-content: space-between; gap: 1rem; align-items: center; max-width: 78rem; margin: 0 auto; padding: 1rem; }\n  .back { display: inline-flex; align-items: center; gap: .45rem; color: #94a3b8; text-decoration: none; font-size: .85rem; }\n  .back:hover, .back:focus-visible { color: #f9fafb; }\n  .help-layout { display: grid; grid-template-columns: minmax(0, 54rem); gap: 3rem; justify-content: center; }\n  .toc { display: none; }\n  .toc nav { position: sticky; top: 1.25rem; max-height: calc(100vh - 2.5rem); overflow-y: auto; border-left: 1px solid #1f2937; padding-left: 1rem; }\n  .toc-title { margin: 0 0 .65rem; color: #f9fafb; font-size: .75rem; font-weight: 700; letter-spacing: .12em; text-transform: uppercase; }\n  .toc ul { display: grid; gap: .15rem; list-style: none; margin: 0; padding: 0; }\n  .toc a { display: block; border-radius: .35rem; color: #94a3b8; font-size: .8rem; line-height: 1.35; padding: .3rem .45rem; text-decoration: none; }\n  .toc a:hover, .toc a:focus-visible { background: #111827; color: #dbeafe; outline: none; }\n  .toc-depth-2 { padding-left: .9rem !important; }\n  .toc-depth-3 { padding-left: 1.8rem !important; font-size: .75rem !important; }\n  @media (min-width: 1024px) { .help-layout { grid-template-columns: minmax(0, 54rem) 16rem; justify-content: center; } .toc { display: block; } }\n  @media (min-width: 640px) { main { padding: 3rem 1.5rem 6rem; } }\n";
 function Vi(e = !1) {
-	let t = W.parse(Ri, { async: !1 });
+	let t = /* @__PURE__ */ new Map(), n = (e) => {
+		let n = e.replace(/[`*_~]/g, "").replace(/\[([^\]]+)\]\([^)]*\)/g, "$1").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "section", r = t.get(n) || 0;
+		return t.set(n, r + 1), r ? `${n}-${r + 1}` : n;
+	}, r = W.lexer(Ri).filter((e) => e.type === "heading" && (e.depth || 0) <= 3).map((e) => ({
+		depth: e.depth,
+		text: e.text || "",
+		id: n(e.text || "")
+	}));
+	t.clear();
+	let i = 0, a = new W.Renderer();
+	a.heading = ({ text: e, depth: t }) => `<h${t} id="${r[i++]?.id || n(e)}">${e}</h${t}>`;
+	let o = W.parse(Ri, {
+		async: !1,
+		renderer: a
+	}), s = (e) => e.replace(/[&<>"']/g, (e) => ({
+		"&": "&amp;",
+		"<": "&lt;",
+		">": "&gt;",
+		"\"": "&quot;",
+		"'": "&#39;"
+	})[e] || ""), c = r.length ? `<aside class="toc"><nav aria-label="On this page"><p class="toc-title">On this page</p><ul>${r.map((e) => `<li><a class="toc-depth-${e.depth}" href="#${e.id}">${s(e.text)}</a></li>`).join("")}</ul></nav></aside>` : "";
 	return `<!doctype html>
 <html lang="en" class="dark">
   <head>
@@ -5562,7 +5582,7 @@ function Vi(e = !1) {
   </head>
   <body>
     ${e ? "" : `<div class="topbar"><a class="back" href="/runs">${zi}<span>Back to jobs</span></a><a class="back" href="/workflows">Manage workflows</a></div>`}
-    <main><article>${t}</article></main>
+    <main><div class="help-layout"><article>${o}</article>${e ? "" : c}</div></main>
   </body>
 </html>`;
 }
@@ -10917,7 +10937,7 @@ async function _l(e) {
 	})), b = jl(n, "running", p, f, _.env, y, s);
 	await o.saveReport(n.id, b), hl(r, n.id);
 	try {
-		Object.assign(_.env, await xl(l.env, _)), Ol(l.secretFiles, a.getAll(), g), v = l.cache ? String(await Zn.evaluateValue(l.cache.key, _)) : "", v && l.cache && await Dl(o, "cache", `${n.workflow_id}:${v}`, l.cache.paths, g), b.environment = { ..._.env }, await o.saveReport(n.id, b);
+		Object.assign(_.env, await xl(l.env, _)), Ol(l.secretFiles, a.getAll(), g), v = l.cache ? String(await Zn.evaluateValue(l.cache.key, _)) : "", v && l.cache && await Dl(o, "cache", `${n.workflow_id}:${v}`, l.cache.paths, g), await o.saveReport(n.id, b);
 	} catch (e) {
 		b.status = "failed", b.finishedAt = (/* @__PURE__ */ new Date()).toISOString(), b.durationMs = Date.now() - p;
 		let r = {

package/dist/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAGL,YAAY,EAOZ,WAAW,EAKZ,MAAM,YAAY,CAAC;AAQpB,eAAO,MAAM,aAAa;;CAEzB,CAAC;AAMF;;GAEG;AACH,wBAAsB,qBAAqB,kBAK1C;AAED,wBAAgB,qBAAqB,SAIpC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,mBAK1G;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,YAAY,iBA0ErB;AAmGD;;GAEG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,WAAW,iBAiH9C"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAGL,YAAY,EAOZ,WAAW,EAKZ,MAAM,YAAY,CAAC;AAQpB,eAAO,MAAM,aAAa;;CAEzB,CAAC;AAMF;;GAEG;AACH,wBAAsB,qBAAqB,kBAK1C;AAED,wBAAgB,qBAAqB,SAIpC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,mBAK1G;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,YAAY,iBA0ErB;AAmGD;;GAEG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,WAAW,iBAgH9C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloud-cli/on",
-  "version": "1.34.2",
+  "version": "1.35.0",
   "description": "CLI entry point for the on plugin ecosystem.",
   "type": "module",
   "packageManager": "pnpm@10.30.3",