@kici-dev/compiler 0.1.23 → 0.1.25

package/dist/llm-context/llms-features.txt

@@ -641,7 +641,7 @@ env: async (event) => {
 
 Source: https://docs.kici.dev/user/env-vars/
 
-The KiCI CLI reads the following environment variables to customize its behavior. OAuth login (`kici login` without `--token`) defaults `KICI_PLATFORM_URL`, `KICI_OIDC_ISSUER`, and `KICI_OIDC_CLIENT_ID` to the hosted KiCI Platform, so `kici login` works with no configuration. Set them only to target a self-hosted Platform or a testing environment.
+The KiCI CLI reads the following environment variables to customize its behavior. OAuth login (`kici login` without `--token`) defaults `KICI_PLATFORM_URL`, `KICI_OIDC_ISSUER`, and `KICI_OIDC_CLIENT_ID` to the hosted KiCI Platform, so `kici login` works with no configuration. Set them only to target another KiCI environment (e.g. a testing instance) or a custom OIDC provider.
 
 ## Authentication
 
@@ -676,9 +676,9 @@ Authenticate with a pre-existing API key (no browser needed):
 kici login --token <<< "$KICI_API_KEY"
 ```
 
-### Self-hosted Platform or custom OIDC provider
+### Targeting another environment or custom OIDC provider
 
-`kici login` targets the hosted KiCI Platform by default. To point the CLI at a self-hosted Platform or a testing OIDC provider, override the defaults:
+`kici login` targets the hosted KiCI Platform by default. To point the CLI at another KiCI environment (e.g. a testing instance) or a custom OIDC provider, override the defaults:
 
 ```bash
 export KICI_OIDC_ISSUER=https://your-idp.example.com
@@ -802,6 +802,36 @@ job('deploy-review', {
 
 A pure function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated inline at dispatch with no init-job overhead. Dynamic environments that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
 
+### Multiple environments per job
+
+A job can bind more than one environment with `environments`, an ordered array. This lets a single job draw secrets and variables from several environments at once — for example a shared `staging` environment plus a `my-testing` environment that carries test-only variables:
+
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  environments: ['staging', 'my-testing'],
+  steps: [
+    step('deploy', async (ctx) => {
+      // ctx.secrets and ctx.env carry the merged set from both environments
+      const dbUrl = await ctx.secrets.get('DB_URL');
+    }),
+  ],
+});
+```
+
+- `environment` (singular) and `environments` (array) are mutually exclusive — setting both is a compile error. `environment: 'staging'` is exactly equivalent to `environments: ['staging']`.
+- Each array entry is a static name or a function of the event, resolved per element exactly like a single dynamic environment.
+
+**Merge order — last wins.** All bound environments are resolved on every dispatch (webhook, scheduled, and test runs alike) and merged in array order. When the same secret or variable key is defined in more than one environment, the later entry in the array wins. With `environments: ['staging', 'my-testing']`, a key defined in both resolves to `my-testing`'s value; keys defined in only one are preserved. The longest-scope-path-wins rule still applies _within_ each environment.
+
+**Protection rules combine all-must-pass.** A job must satisfy **every** bound environment's gates — adding an environment can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all environments; the minimum trust tier is the most restrictive across them; required reviewers are the union of all environments' reviewers; the wait timer is the longest; and the hold expiry is the shortest. If a run is gated out, the rejection names which environment and which rule rejected it (visible via `kici runs show <run-id>` and the run's rejection reason), so a mutually-exclusive set of rules surfaces as a clear failure rather than a silent perpetual rejection.
+
+**Skip-on-test (allow-and-warn).** On a test or local run (`kici run remote`, `kici run local`), a bound environment never rejects the run. Any bound environment that disallows local execution (`allowLocalExecution: false`) — or that is not configured — is **skipped**: its variables and secrets are omitted from the merge and its gates are not evaluated. The run proceeds, and a user-visible warning naming the skipped environment(s) is shown both on the `kici run remote` CLI output and on the dashboard run view. This makes the test-only-variables pattern work: with `environments: ['staging', 'my-testing']` where only `my-testing` allows local execution, a test run resolves just `my-testing`'s variables and warns that `staging` was skipped. If every bound environment is skipped, the job runs with no environment variables. This is intentionally different from a fixture `secrets:` mapping, which is fail-closed — see the [testing guide](https://docs.kici.dev/user/testing-guide/).
+
+**Unconfigured environments contribute nothing at dispatch.** At dispatch time a bound environment name with no matching configured environment (and no matching glob environment) simply adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic environment resolving to an as-yet-unconfigured name does today.
+
+**Registration rejects a provably-unsatisfiable binding.** When a workflow is registered, KiCI statically checks every multi-environment binding: a bound environment that does not exist, a disabled one, or two environments with mutually-exclusive fixed branch / trigger-type / repository restrictions (no value can satisfy both) makes the binding provably unsatisfiable, and the registration is rejected with a precise message naming the job, the environments, and the rule — for example `unsatisfiable environment binding: job 'deploy' binds environments [staging, my-testing] with mutually exclusive branch restrictions (no value satisfies all bound environments)`. Bindings whose restrictions use globs are undecidable at registration and fall through to the dispatch-time gate check instead.
+
 ### Job-level environment variables
 
 The `env` property on a job provides static or dynamic environment variables:
@@ -841,25 +871,30 @@ job('deploy', {
 });
 ```
 
-If no `concurrencyGroup` is specified, the environment name is used as the default concurrency group.
+If no `concurrencyGroup` is specified, the environment name is used as the default concurrency group. For a job bound to multiple environments, the default is the **first** bound environment's name.
 
 ### Step context
 
 Inside a step, the `ctx` object provides:
 
-| Property          | Type                                  | Description                                                                  |
-| ----------------- | ------------------------------------- | ---------------------------------------------------------------------------- |
-| `ctx.environment` | `string \| undefined`                 | Resolved environment name (undefined for jobs without environment)           |
-| `ctx.env`         | `Record<string, string \| undefined>` | Environment variables (merged from system, org, source, and job-level `env`) |
-| `ctx.secrets`     | `StepSecretsTyped`                    | Async accessor for bound secrets (get, expose, has, getMeta)                 |
-
-| Method                          | Returns                   | Description                                                                                                                       |
-| ------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `await ctx.secrets.get(key)`    | `string`                  | Retrieve a secret value. Throws `SecretNotFoundError` if not found.                                                               |
-| `await ctx.secrets.expose(key)` | `void`                    | Inject a secret into the step's environment variables (`ctx.env`). Throws `SecretNotFoundError` if not found.                     |
-| `ctx.secrets.has(key)`          | `boolean`                 | Check if a secret key exists. Synchronous, never throws.                                                                          |
-| `ctx.secrets.getMeta(key)`      | `SecretMeta \| undefined` | Retrieve metadata (value, backend name, scope path) for a resolved secret. Returns `undefined` if not found.                      |
-| `ctx.setSecretOutput(key, val)` | `void`                    | Publish an encrypted secret output from this job, consumable by downstream jobs via `needs`. Never logged or stored in plaintext. |
+| Property          | Type                                  | Description                                                                               |
+| ----------------- | ------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `ctx.environment` | `string \| undefined`                 | Resolved environment name (undefined for jobs without environment)                        |
+| `ctx.env`         | `Record<string, string \| undefined>` | Environment variables (merged from system, org, source, and job-level `env`)              |
+| `ctx.secrets`     | `StepSecretsTyped`                    | Async accessor for bound secrets (get, expose, has, getMeta, list, mountFile, exposeFile) |
+
+| Method                                       | Returns                   | Description                                                                                                                                                        |
+| -------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `await ctx.secrets.get(key)`                 | `string`                  | Retrieve a secret value. Throws `SecretNotFoundError` if not found.                                                                                                |
+| `await ctx.secrets.expose(key)`              | `void`                    | Set the secret as an environment variable for this step — visible via `ctx.env` and to child processes (`process.env`). Throws `SecretNotFoundError` if not found. |
+| `ctx.secrets.has(key)`                       | `boolean`                 | Check if a secret key exists. Synchronous, never throws.                                                                                                           |
+| `ctx.secrets.getMeta(key)`                   | `SecretMeta \| undefined` | Retrieve metadata (value, backend name, scope path) for a resolved secret. Returns `undefined` if not found.                                                       |
+| `ctx.secrets.list()`                         | `string[]`                | Every secret key available to the step, sorted alphabetically. Synchronous, never throws.                                                                          |
+| `await ctx.secrets.mountFile(opts)`          | `{ path }`                | Materialise one or more secrets to a per-step tmpfile (auto-removed at step end). See [Secrets → Mounting secrets as files](https://docs.kici.dev/user/secrets/#mounting-secrets-as-files). |
+| `await ctx.secrets.exposeFile(envVar, opts)` | `{ path }`                | `mountFile` plus `process.env[envVar] = path`; the env var is unset at step end.                                                                                   |
+| `ctx.setSecretOutput(key, val)`              | `void`                    | Publish an encrypted secret output from this job, consumable by downstream jobs via `needs`. Never logged or stored in plaintext.                                  |
+
+The full secrets API — including `SecretFileOptions`, log masking, and the canonical `sops` example — is documented in [Secrets](https://docs.kici.dev/user/secrets/).
 
 ## Environment variable merge precedence
 
@@ -982,6 +1017,12 @@ Each environment has four tabs:
 
 4. **History** -- view filtered runs targeting this environment.
 
+### Bound environments on runs
+
+A job's bound deployment environments are shown as chips on the run detail page (in the job metadata panel) in the order the job declared them, and the distinct set across a run's jobs appears as compact chips on the run list. For a multi-environment job the chips read left-to-right in merge order — later environments override earlier ones on key collisions. A `(dynamic)` chip marks an environment whose name is computed at runtime; it resolves to the real name once the run starts. A job that binds a single environment shows one chip; a job that binds none shows no chip.
+
+If a multi-environment binding is gated out, the run's failure banner names which environment and which rule rejected it (the same all-must-pass detail surfaced by `kici runs show <run-id>`).
+
 ### Secrets management
 
 Secrets are individual encrypted values organized by scope paths (e.g., `aws/prod`, `databases/postgres`). Scopes are bound to environments via bindings:
@@ -2005,11 +2046,34 @@ statement's build context must match the token's identity claims (a mismatch is
 a hard failure).
 
 ```bash
-kici verify-attestation [artifact] --bundle <path-or-url> --trust-root <url-or-file>
+kici verify-attestation [artifact] --bundle <path-or-url> [--trust-root <url-or-file>]
 ```
 
-You supply the trusted issuer out-of-band via `--trust-root` — the verifier
-never trusts the issuer named inside the token. There are two forms:
+### Which trust root do I use?
+
+The trust root is the **KiCI platform's provenance issuer** — the same hosted
+KiCI platform you `kici login` against. KiCI attestations are issued by, and
+verified against, that one issuer; there are no competing "roots" to choose
+between. So the answer to "shouldn't I just use KiCI as the trust root?" is yes
+— and that's the **default**: omit `--trust-root` and the verifier checks the
+bundle against the hosted KiCI platform automatically. You only pass
+`--trust-root` to verify against a different environment or, more commonly, an
+offline `{ issuer, jwks }` file for air-gapped checks.
+
+### Why you supply it out-of-band
+
+Given there's a single issuer, why pass it at all instead of letting the
+verifier read it from the token? Because the issuer named **inside** a token
+cannot be trusted: a forged bundle could carry a token that names
+`iss: https://attacker.example` _and_ bundle a key set that "verifies" it,
+making the whole signature chain circular and self-attesting. The verifier
+therefore pins to an issuer you supply out-of-band and checks the token against
+_that_ — the bundle is verified against a key set you trust, not one it shipped
+with. Naming the trust root is a security requirement, not a multiple-choice
+question.
+
+To override the default, supply the trusted issuer via `--trust-root`, in one of
+two forms:
 
 - **Online — an HTTPS issuer URL.** The verifier fetches
   `<url>/.well-known/openid-configuration`, reads its `issuer` and `jwks_uri`,
@@ -2037,7 +2101,10 @@ when it does not (or on an error such as a missing flag or unreachable trust
 root).
 
 ```bash
-# Verify a bundle against a deployed issuer, digest-checking the artifact:
+# Default: verify against the hosted KiCI platform (no --trust-root needed):
+kici verify-attestation ./dist/app.tgz --bundle ./app.tgz.kici.json
+
+# Override the trust root to verify against a specific issuer:
 kici verify-attestation ./dist/app.tgz \
   --bundle ./app.tgz.kici.json \
   --trust-root https://platform.example/issuer
@@ -2076,6 +2143,44 @@ attestations shows an empty state.
 
 <!-- /help:run-attestations -->
 
+## Browsing attestations across runs
+
+The **Attestations** page (in the org sidebar) lists every build-provenance
+attestation your organization has produced — not just one run's. It is the
+supply-chain audit surface: look up "who built `sha256:…`?" by digest, or browse
+and filter every attestation across all runs.
+
+<!-- help:attestations-list#browsing-attestations-across-runs -->
+
+The **Attestations** page lists every build-provenance attestation your organization has produced.
+
+- **Search** by artifact digest (exact `sha256:…`) or name to trace a specific artifact.
+- **Filter** by verification status, repository, workflow, job, or date.
+- Each row's **status badge** is the verdict KiCI recorded when the attestation was produced (`verified`, `failed`, `unverifiable`, or `pending`).
+
+Open a row for the parsed provenance statement and a live re-verification.
+
+<!-- /help:attestations-list -->
+
+The status badge here is the **server-side verdict**, computed once when the
+attestation was recorded (verify-at-ingest) — so the list stays fast at any
+size. `verified` means the signature, build identity, and build context all
+checked out against the provenance issuer; `failed` means verification ran and
+the bundle did not pass; `unverifiable` means no verdict could be computed (no
+provenance issuer configured, or its keys could not be read — not a forgery
+signal); `pending` means the verdict has not been computed yet.
+
+Opening a row leads to the **attestation detail page**:
+
+<!-- help:attestation-detail#browsing-attestations-across-runs -->
+
+This page shows the parsed provenance for one attestation.
+
+- **Builder identity, source, and build type** come from the signed SLSA statement.
+- The **stored badge** is the verdict recorded at build time; **Re-verify** runs the check live in your browser against the current signing keys.
+- **Download** exports the signed bundle for offline verification with `kici verify-attestation`.
+<!-- /help:attestation-detail -->
+
 ## See also
 
 - [SDK runtime reference](https://docs.kici.dev/user/sdk/runtime/) — the `ctx.attestProvenance` and
@@ -2097,6 +2202,8 @@ Secrets are managed per-environment in the orchestrator (see [operator docs](htt
 
 This design prevents accidental secret leakage through child processes, log output, or error messages. Only secrets you explicitly request are loaded into memory.
 
+A job can bind several environments with `environments: ['staging', 'my-testing']`; the secret keys from all bound environments are merged in array order, with a later environment's value winning on a key collision. See [Multiple environments per job](https://docs.kici.dev/user/environments/#multiple-environments-per-job).
+
 ## Where secret values come from
 
 Secret values are written either through the dashboard or through `kici-admin` running against the orchestrator. The orchestrator operator decides — per organization — which surface accepts secret writes. From the workflow author's perspective, the resolution path at run time is identical either way; the difference is where you (or your ops team) **enter** the value.