@kici-dev/compiler 0.1.22 → 0.1.23

package/dist/llm-context/llms-getting-started.txt

@@ -0,0 +1,519 @@
+# KiCI Getting started
+
+This bundle covers: Install the SDK, write your first workflow, compile and test locally.
+
+## User guide
+
+Source: https://docs.kici.dev/user/
+
+Documentation for workflow authors -- people writing CI/CD pipelines in TypeScript using the KiCI SDK and compiler. If you are defining workflows, running local tests, or learning the SDK API, start here.
+
+## Pages
+
+### [Getting started with KiCI](https://docs.kici.dev/user/getting-started/)
+
+Install the SDK and compiler, write your first workflow, compile it to a lock file, and test it locally with simulated events. Covers prerequisites (Node.js 24+, pnpm), the `kici init` command for scaffolding, and the relationship between workflows, the lock file, and the three-tier runtime.
+
+### [SDK reference](https://docs.kici.dev/user/sdk-reference/)
+
+Complete API reference for `@kici-dev/sdk`. Covers all factory functions (`workflow()`, `job()`, `step()`), trigger builders (`pr()`, `push()`), rule functions (`rule()`, `skip()`), matrix configuration (static arrays, static objects, dynamic functions, include/exclude), and the `StepContext` interface that steps receive at runtime.
+
+### [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/)
+
+Why the lock file must stay in sync with workflow source, how to commit both together, using pre-commit and CI to catch drift early, and the agent-side hash verification when compiling from source.
+
+### [CLI reference](https://docs.kici.dev/user/cli-reference/)
+
+All CLI commands provided by `@kici-dev/compiler`: `kici compile` (with watch mode and check mode), `kici run` (local and remote execution), `kici test` (event simulation with dry-run, filtering, debug output, and custom payloads), `kici login`/`logout`/`org` (authentication and org management), `kici diagnostics` (infrastructure tree) and `kici runs` (`list`/`show`/`logs`/`rerun`/`cancel` — run management), `kici secrets` (secret listing), `kici types` (type generation), `kici fixture` (generate test payloads), `kici init` (interactive project scaffolding), `kici hook` (pre-commit hook installation), `kici endpoints` (webhook entrypoints), and `kici workflows` (workflow listing). Includes environment variables and exit codes.
+
+### [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/)
+
+Common patterns for building real-world CI/CD workflows. Includes examples for basic CI pipelines with job dependencies, monorepo path-based triggering, conditional jobs with rules, matrix builds across Node versions, dynamic jobs generated at runtime, Docker-based step execution, and parallel test splitting.
+
+### [Dashboard](https://docs.kici.dev/user/dashboard/)
+
+Guide to the KiCI web dashboard. Covers navigation (sidebar, org switcher, mobile bottom tabs), run list (table columns, filters, pagination, empty states), run detail (resizable two-panel layout, job tree, step selection, metadata tabs), log viewer (ANSI color rendering, search, permalink, copy), settings page (tabbed layout), theme toggle, keyboard shortcuts, and error pages.
+
+### [Testing guide](https://docs.kici.dev/user/testing-guide/)
+
+How to run and write tests for KiCI workflows, including remote test execution with `kici run remote`, fixture-based testing, and overlay mode for uncommitted changes.
+
+### [Environments](https://docs.kici.dev/user/environments/)
+
+Configure deployment environments (staging, production, review/\*) with variables, scoped secrets, and protection rules. Covers the SDK API (`environment`, `env`, `concurrencyGroup` on jobs), the 8-layer variable merge precedence, protection rules (branch restrictions, required reviewers, wait timers, concurrency), dashboard management, type generation, and migration from the legacy contexts system.
+
+### [Environment variables](https://docs.kici.dev/user/env-vars/)
+
+Reference for all `KICI_*` environment variables supported by the CLI. Covers authentication overrides (OIDC issuer, client ID, project ID), browser behavior (custom browser command, fixed callback port), development mode, and usage examples for CI/CD, self-hosted, and headless environments.
+
+### [CLI authentication](https://docs.kici.dev/user/cli-auth/)
+
+Authenticate the KiCI CLI with browser-based OAuth (default), device authorization flow (for headless environments), or API key paste (for CI/CD pipelines). Covers org management and PATs.
+
+### [Event system](https://docs.kici.dev/user/events/)
+
+Event model concepts: event types, the registration model, event matching, and circuit breaker protection. Understanding this distinction is key to working with non-git triggers like schedules, custom events, and generic webhooks.
+
+### [Lifecycle hooks](https://docs.kici.dev/user/hooks/)
+
+SDK hook API for cancel, cleanup, success, failure, and step-level callbacks. Hooks run at specific points in the execution lifecycle to react to outcomes and perform cleanup.
+
+### [Concurrency groups](https://docs.kici.dev/user/concurrency/)
+
+Control parallel execution with auto-cancel and queue modes. Prevent multiple workflow runs from executing in parallel when they target the same resource.
+
+### [Dynamic values](https://docs.kici.dev/user/dynamic-values/)
+
+Compute `environment`, `env`, and `concurrencyGroup` at runtime based on the incoming event payload. Instead of hardcoding static strings, pass a function that receives the webhook event and returns the resolved value.
+
+### [Secrets](https://docs.kici.dev/user/secrets/)
+
+Access encrypted secrets in workflow steps via the explicit secrets API. Secrets are never auto-injected into `process.env` -- you must explicitly request each secret by name.
+
+### [GitHub App provider](https://docs.kici.dev/user/providers/github/)
+
+The flagship source. Covers creating the GitHub App on GitHub's side (permissions, webhook URL, private key), registering it with the orchestrator via `kici-admin source add github`, routing keys (`github:<appId>`), global-workflow policy, enriched Check runs on pull requests, private-key and webhook-secret rotation, and troubleshooting.
+
+### [Universal-git provider](https://docs.kici.dev/user/providers/universal-git/)
+
+Connect a non-GitHub-App forge (Forgejo, Gitea, Gogs, GitLab, plain GitHub) to KiCI via its webhook. Covers preset selection, PAT and SSH credential wiring, credential rotation, global workflow policy against `generic:<orgId>:<sourceId>` routing keys, and troubleshooting.
+
+### [Global workflows](https://docs.kici.dev/user/global-workflows/)
+
+Cross-repo workflows that let a single workflow repo define jobs which run on events from many source repos in the same org. Covers the mental model (workflow repo vs. source repo, authoring axis vs. source axis), SDK syntax for declaring globals via `repos:` patterns, the dashboard opt-in flow and per-setting semantics (master toggle, author allow-list, source deny-list, elevated-access list), the security model, and troubleshooting skipped dispatches.
+
+---
+
+## Getting started with workflows
+
+Source: https://docs.kici.dev/user/getting-started/
+
+KiCI lets you define CI/CD workflows in TypeScript instead of YAML. You get full language power -- type safety, autocompletion, loops, conditionals, and async/await -- for your build pipelines.
+
+## Prerequisites
+
+- **Node.js 24+** (LTS recommended)
+- **pnpm** (or npm/yarn -- examples use pnpm)
+- Familiarity with TypeScript
+
+## Quick start with kici init
+
+The recommended way to start a new project is `kici init`. It scaffolds the directory structure, lets you pick a starter template, and installs dependencies for you:
+
+```bash
+npx kici init
+```
+
+This will:
+
+1. Create `.kici/` directory with `workflows/`, `tests/`, `types/`, `package.json`, and `tsconfig.json`
+2. Create a `.kiciignore` file with sensible defaults
+3. Let you choose from starter workflow templates (hello-world, pr-checks)
+4. Install dependencies using the package manager detected for your repo (npm, pnpm, or yarn)
+5. Update `.gitignore` to exclude `.kici/node_modules/`
+6. Optionally install a pre-commit hook to auto-compile workflows
+
+The package manager is detected from your repo's `packageManager` field, lockfile, or the manager that invoked `kici`, defaulting to npm. Pass `--package-manager <npm|pnpm|yarn>` to override it.
+
+### Options
+
+| Flag                                  | Description                                                  |
+| ------------------------------------- | ------------------------------------------------------------ |
+| `--force`                             | Overwrite existing `.kici/` directory                        |
+| `--skip-install`                      | Create files without installing dependencies                 |
+| `--package-manager <npm\|pnpm\|yarn>` | Force a package manager for the install step (default: auto) |
+| `--mjs`                               | JavaScript-only mode (no TypeScript, no deps)                |
+
+### MJS mode
+
+If you prefer plain JavaScript without TypeScript compilation:
+
+```bash
+npx kici init --mjs
+```
+
+This creates `.mjs` workflow files that run directly without a build step.
+
+After running `kici init`, jump straight to [Compile the workflow](https://docs.kici.dev/user/getting-started/#compile-the-workflow) below to compile and preview the scaffolded workflow.
+
+## Manual setup
+
+If you'd rather wire things up by hand instead of using `kici init`, install the SDK (runtime definitions) and the compiler (CLI tooling) yourself, then create your first workflow.
+
+### Install the SDK and compiler
+
+```bash
+pnpm add @kici-dev/sdk
+pnpm add -D @kici-dev/compiler
+```
+
+The examples use pnpm, but npm and yarn work too. With npm:
+
+```bash
+npm install @kici-dev/sdk
+npm install -D @kici-dev/compiler
+```
+
+With yarn:
+
+```bash
+yarn add @kici-dev/sdk
+yarn add -D @kici-dev/compiler
+```
+
+### Create the workflow directory
+
+KiCI looks for workflows in `.kici/workflows/`:
+
+```bash
+mkdir -p .kici/workflows
+```
+
+### Write a workflow
+
+Create `.kici/workflows/ci.ts`:
+
+```typescript
+import { workflow, job, step, pr } from '@kici-dev/sdk';
+
+const lint = job('lint', {
+  runsOn: 'linux',
+  steps: [
+    step('install', async ({ $ }) => {
+      await $`pnpm install --frozen-lockfile`;
+    }),
+    step('lint', async ({ $ }) => {
+      await $`pnpm lint`;
+    }),
+  ],
+});
+
+const test = job('test', {
+  runsOn: 'linux',
+  needs: [lint],
+  steps: [
+    step('install', async ({ $ }) => {
+      await $`pnpm install --frozen-lockfile`;
+    }),
+    step('run-tests', async ({ $ }) => {
+      await $`pnpm test`;
+    }),
+  ],
+});
+
+export default workflow('ci', {
+  on: pr({ target: 'main' }),
+  jobs: [lint, test],
+});
+```
+
+This workflow:
+
+- Triggers on pull requests targeting `main`
+- Runs a `lint` job first
+- Runs a `test` job after lint succeeds (`needs: [lint]`)
+
+`runsOn` selects which agents may run a job. Every agent self-reports `kici:os:<platform>`, `kici:arch:<cpu>`, and `kici:host:<hostname>`, so `runsOn: 'kici:os:linux'` targets any connected Linux agent with zero configuration — `kici init` scaffolds workflows with exactly that. Use a custom label such as `'linux'` or `'gpu'` (defined in your scaler's `labelSet`) to target a specific pool instead. See the [runsOn forms](https://docs.kici.dev/user/sdk/core/#runson-forms) reference for the full label model.
+
+**Single-step shortcut.** If a job only has one step, pass `run` directly to `job()` instead of building a `steps: [step(...)]` array:
+
+```typescript
+const deploy = job('deploy', {
+  runsOn: 'default',
+  run: async ({ $, log }) => {
+    await $`./scripts/deploy.sh`;
+    log.info('Deployed');
+  },
+});
+```
+
+`run` and `steps` are mutually exclusive. The shorthand is ideal for deploy/notify/smoke-test jobs. See [Single-step job shorthand](https://docs.kici.dev/user/sdk/core/#single-step-job-shorthand) in the SDK reference for details (output access on the resulting `job.result` is flat -- no step-name nesting).
+
+## Compile the workflow
+
+The compiler validates your workflow and generates a lock file:
+
+```bash
+npx kici compile
+```
+
+Expected output:
+
+```
+✓ Compiled workflows → .kici/kici.lock.json (1 workflow)
+```
+
+The lock file (`kici.lock.json`) is a JSON representation of your workflow that the KiCI agent uses for execution. Commit this file alongside your workflow source. See [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/) for why and how to keep them in sync.
+
+## Preview trigger matching
+
+Use `kici test` to preview which workflows match a trigger event (dry-run, no execution):
+
+```bash
+npx kici test pr:open
+```
+
+Expected output (simplified):
+
+```
+🔍 DRY RUN - No commands will be executed
+
+Workflow: ci
+  Triggers:
+    - pr
+  ✓ Matched trigger 1
+  Jobs (2):
+    lint
+      runs-on: linux
+    test
+      runs-on: linux
+
+Decision Summary:
+
+  ci: ✓ matched
+
+✓ Dry run complete
+```
+
+## Run locally
+
+Execute matched workflows locally with `kici run local`:
+
+```bash
+npx kici run local pr:open
+```
+
+This compiles, matches triggers, and runs all matched jobs with DAG-based parallel scheduling.
+
+If you do not want to remember the event arg, pass `--pick` (or `-p`) and pick from a list of workflows instead:
+
+```bash
+npx kici run local --pick
+```
+
+The picker lists each workflow with a summary of its declared triggers, derives the event arg for the one you choose, and runs it through the same pipeline.
+
+## Workflow dependencies
+
+KiCI workflows can use any npm package. Dependencies are declared in `.kici/package.json`, which `kici init` generates automatically.
+
+### Adding dependencies
+
+To add a package to your workflows:
+
+```bash
+cd .kici
+npm install lodash
+```
+
+This updates `.kici/package.json` and generates (or updates) `package-lock.json`.
+
+### Dependency resolution contract
+
+Every `.kici/` dependency must be resolvable from the **single cloned repository**. When a job runs, the agent clones only this repository and installs `.kici/` dependencies with your repo's package manager — npm, pnpm, yarn classic (v1), and yarn berry (v2+). A dependency that points outside the cloned repo cannot be resolved.
+
+In practice:
+
+- **From a registry** — the common case. Pin a published version (a private registry works — see [Private registries](https://docs.kici.dev/user/private-registries/)). Available for any package manager.
+- **From an in-repo workspace sibling** — if your `.kici/` is a member of a **pnpm workspace** or a **yarn berry workspace** (a `workspaces` array in the repo-root `package.json`), it can depend on a sibling package in the same repo via `workspace:*` (yarn berry also accepts `portal:`). The whole repo is cloned, so the sibling is present and resolves; the agent also builds your `.kici/` dependency closure after install, so a sibling's build output exists before the workflow that imports it loads. A `file:`/`link:`/`portal:` path is allowed only when it stays inside the repository.
+
+What fails fast (with an actionable error naming the dependency, not a raw package-manager error): a `workspace:` dependency in an **npm** project (npm has no workspace protocol — pin a published version or switch to pnpm), a `workspace:`/`portal:` dependency in a **yarn classic** project (v1 has neither — use a version range, pnpm, or yarn berry), a `workspace:` dependency in a **yarn berry** project whose repo-root `package.json` has no `workspaces` array, and any `file:`/`link:`/`portal:` path that points outside the cloned repo.
+
+Then use the package in your workflow:
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+import _ from 'lodash';
+
+export default workflow('deploy', {
+  on: push({ branches: 'main' }),
+  jobs: [
+    job('process', {
+      runsOn: 'default',
+      steps: [
+        step('transform', async ({ log }) => {
+          const data = _.merge({ a: 1 }, { b: 2 });
+          log.info(`Merged: ${JSON.stringify(data)}`);
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+### How dependencies are cached
+
+When the KiCI agent runs your workflow, dependencies are handled automatically:
+
+1. **First run (cache miss):** A build agent installs dependencies from `.kici/package.json`, packs the resolved dependency tree into a tarball, and uploads it to cache storage. For a pnpm workspace this closure includes the shared store and any in-repo workspace siblings `.kici` resolves.
+2. **Subsequent runs (cache hit):** The execution agent downloads the cached tarball and extracts it -- no install needed.
+3. **Lockfile changes:** When your lockfile changes (`.kici/package-lock.json` for npm, or the repo-root `pnpm-lock.yaml` for a pnpm workspace), the cache is invalidated and a fresh build runs.
+
+This means the first run after a dependency change is slower (build + execution), but all subsequent runs are fast.
+
+### The .kici/package.json file
+
+Every KiCI project needs a `.kici/package.json`. This file:
+
+- Declares workflow dependencies (including `@kici-dev/sdk`)
+- Signals the agent to run the dependency cache step
+- Is generated automatically by `kici init`
+
+If you are setting up a project manually (without `kici init`), create a minimal `.kici/package.json`:
+
+```json
+{
+  "name": "@kici-dev/workflows",
+  "private": true,
+  "type": "module",
+  "devDependencies": {
+    "@kici-dev/sdk": "^0.0.1"
+  }
+}
+```
+
+Then run `npm install` in `.kici/` to generate the lockfile. Commit both `package.json` and `package-lock.json` to your repository.
+
+## Development mode
+
+When developing the KiCI SDK itself (or testing against a local fork), enable development mode.
+
+### sdkPath in .kici/package.json
+
+Point to a local SDK checkout for IDE autocompletion:
+
+```json
+{
+  "name": "my-project-kici",
+  "devDependencies": {
+    "@kici-dev/sdk": ">=0.0.1-0"
+  },
+  "kici": {
+    "sdkPath": "../../packages/sdk"
+  }
+}
+```
+
+The `sdkPath` field tells the compiler where to resolve TypeScript path mappings for `@kici-dev/sdk`.
+
+### KICI_DEV environment variable
+
+Set `KICI_DEV=true` to use a prerelease-compatible version range (`>=0.0.1-0`) in generated files, which resolves prerelease builds from a local Verdaccio registry:
+
+```bash
+KICI_DEV=true npx kici init
+```
+
+Or add the flag to your root `package.json`:
+
+```json
+{
+  "kici": {
+    "development": true
+  }
+}
+```
+
+## Authoring KiCI workflows with LLM coding agents
+
+KiCI is LLM-ready by design. Because workflows are real, typed TypeScript, coding agents reason over the SDK's `.d.ts` signatures instead of guessing a bespoke YAML DSL — and they verify their own pipelines with the same `kici test` and `kici run local` loop you use, so there's no push-to-find-out round-trip. First-class agent context ships in the box, so an agent is briefed the moment it opens the project.
+
+KiCI ships first-class context for LLM coding agents (Claude Code, Cursor, Aider, etc.). When you scaffold a project with `kici init`, the CLI writes `.kici/AGENTS.md`, a one-page briefing that tells the agent:
+
+- where the SDK type declarations live (`node_modules/@kici-dev/sdk/dist/index.d.ts`)
+- the five canonical authoring patterns with runnable examples
+- the anti-patterns that catch agents off-guard (no YAML, no `/dist/...` imports, no top-level `await`)
+- the local commands the agent should drive (`kici compile --check`, `kici test`, `kici run local`, `kici docs llm`)
+
+If you don't want the file, pass `--no-agents-md` to `kici init`, or delete the file afterwards — KiCI never reads it at runtime.
+
+For coding agents that want the entire documentation set up front, KiCI follows the [llms.txt convention](https://llmstxt.org/):
+
+- `https://kici.dev/llms.txt` — curated link index grouped by SDK / patterns / CLI / architecture.
+- `https://kici.dev/llms-full.txt` — concatenated markdown of every page indexed above.
+- `kici docs llm` — print the same `llms-full.txt` bundle to stdout, offline, straight from the installed `@kici-dev/compiler` package. Add `--index` to print the curated `llms.txt` index instead. The agent can pipe the output into its own context buffer with no network call.
+- `kici docs` — open the docs site in your browser.
+
+The offline bundle is regenerated from `docs/` every time the package is built, so it always matches the version of KiCI you've installed.
+
+## Watch mode
+
+During development, run the compiler in watch mode to recompile automatically when workflows change:
+
+```bash
+npx kici compile --watch
+```
+
+The compiler watches `.kici/workflows/*.ts` and recompiles on every save.
+
+## Next steps
+
+- **[5-minute quickstart](https://docs.kici.dev/user/quickstart/)** -- ready to run your workflow on real infrastructure? Stand up an orchestrator + agent (Docker / Podman or bare metal)
+- **[SDK reference](https://docs.kici.dev/user/sdk-reference/)** -- complete API for workflows, jobs, steps, triggers, rules, and matrix
+- **[CLI reference](https://docs.kici.dev/user/cli-reference/)** -- all CLI commands with options and examples
+- **[Workflow patterns](https://docs.kici.dev/user/workflow-patterns/)** -- common patterns for real-world CI/CD workflows
+
+## How KiCI works
+
+KiCI uses a three-layer architecture:
+
+```
+SDK (define) -> Compiler (validate) -> Lock file -> Agent (execute)
+```
+
+1. **SDK**: You write workflows in TypeScript using factory functions (`workflow()`, `job()`, `step()`). The SDK provides type-safe definitions with full IDE support.
+
+2. **Compiler**: The `kici compile` command loads your TypeScript workflows, validates the dependency graph (no cycles, no missing references), and generates `kici.lock.json`.
+
+3. **Lock file**: A portable JSON file containing all workflow metadata. The lock file enables the orchestrator to evaluate triggers without cloning your repository.
+
+4. **Agent**: The agent receives dispatch instructions, clones your repository, and executes the steps defined in your workflows. Agents are self-hosted and label-routed.
+
+The lock file approach means the orchestrator stays git-agnostic -- it only needs the lock file to decide which jobs to run. The agent handles the actual code checkout and step execution.
+
+## See also
+
+- [SDK reference](https://docs.kici.dev/user/sdk-reference/) -- complete API for workflows, jobs, steps, triggers, rules, and matrix
+- [CLI reference](https://docs.kici.dev/user/cli-reference/) -- all CLI commands with options and examples
+- [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/) -- common patterns for real-world CI/CD workflows
+- [Architecture overview](https://docs.kici.dev/architecture/overview/) -- how the three-tier runtime executes your workflows
+
+---
+
+## 5-minute quickstart
+
+Source: https://docs.kici.dev/user/quickstart/
+
+KiCI offers two equally-supported quickstart paths. Pick the one that fits your machine — both end with the same working pipeline (orchestrator + agent + your first workflow run visible in the dashboard).
+
+Each guide is split into two parts. **Part 1** gets you a green run against your own orchestrator with `kici run remote` — no GitHub App needed, just sign up, bring up the stack, and run. **Part 2** then wires up real GitHub pushes so your team's commits trigger runs automatically. You can stop after Part 1 and come back to Part 2 whenever you're ready.
+
+## Option A — Docker / Podman (recommended)
+
+Two containers brought up with `docker compose up -d` (orchestrator + PostgreSQL), plus one short-lived agent container spawned per job by the container scaler. Minimal host setup, perfect for a laptop, home server, or a tiny VM. No need to install PostgreSQL or any other system service.
+
+[Start with the Docker / Podman quickstart →](https://docs.kici.dev/user/quickstart/compose/)
+
+## Option B — Bare-metal install
+
+Native systemd services managed by `kici-admin orchestrator install` / `kici-admin agent install` — the orchestrator and agents run as native processes. The backing PostgreSQL runs as a single container by default (one `docker compose up -d`), or you can install it natively if you'd rather not run a container runtime at all. Best for a long-lived Linux host.
+
+[Start with the bare-metal quickstart →](https://docs.kici.dev/user/quickstart/bare-metal/)
+
+## Which should I pick?
+
+|                           | Docker / Podman                          | Bare metal                                                                            |
+| ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------- |
+| Host requirements         | `docker` or `podman` with compose v2.20+ | systemd, Node.js 24+, PostgreSQL 18 (container — needs `docker`/`podman` — or native) |
+| First local run (Part 1)  | ~5 minutes                               | ~10 minutes                                                                           |
+| First GitHub run (Part 2) | + ~10 minutes                            | + ~10 minutes                                                                         |
+| Upgrades                  | `docker compose pull` + restart          | `kici-admin orchestrator restart` after `npm install -g kici-admin@latest`            |
+| Best for                  | Quick evaluation, ephemeral hosts        | Long-lived production hosts                                                           |
+
+If you're not sure, pick Docker / Podman.
+
+## Looking for the laptop-only path?
+
+Both quickstarts deploy a real orchestrator + agent. If you only want to write a workflow and dry-run it on your laptop with no infrastructure, [Getting started](https://docs.kici.dev/user/getting-started/) covers `kici test` and `kici run local` instead.
+
+---