@kici-dev/compiler 0.1.26 → 0.1.27

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

@@ -38,7 +38,7 @@ Guide to the KiCI web dashboard. Covers navigation (sidebar, org switcher, mobil
 
 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/)
+### [Contexts](https://docs.kici.dev/user/contexts/)
 
 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.
 
@@ -277,21 +277,13 @@ Decision Summary:
 
 ## Run locally
 
-Execute matched workflows locally with `kici run local`:
+Execute matched workflows locally with `kici run <event> --local`:
 
 ```bash
-npx kici run local pr:open
+npx kici run pr:open --local
 ```
 
-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.
+This compiles, matches triggers, and runs all matched jobs on this machine — which joins as an ephemeral agent through the warm local dev plane — with DAG-based parallel scheduling.
 
 ## Workflow dependencies
 
@@ -416,14 +408,14 @@ Or add the flag to your root `package.json`:
 
 ## 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 preview` 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 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 preview` and `kici run <event> --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 preview`, `kici run local`, `kici docs llm`)
+- the local commands the agent should drive (`kici compile --check`, `kici preview`, `kici run <event> --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.
 
@@ -514,6 +506,6 @@ 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 preview` and `kici run local` instead.
+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 preview` and `kici run <event> --local` instead.
 
 ---

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

@@ -194,7 +194,7 @@ Sometimes you want a workflow that does **not** fire on pushes, pull requests, t
 
 There are two ways to "explicitly invoke" a `dispatch()` workflow:
 
-1. **Locally from your laptop**, with `kici run local dispatch` — no orchestrator, no agent, no webhook, nothing deployed. This is the only path while you haven't wired the repo to a deployed KiCI orchestrator.
+1. **Locally from your laptop**, with `kici run dispatch --local` — this machine joins as an ephemeral agent through the warm local dev plane, so no orchestrator deployment is required. This is the path to use while you haven't wired the repo to a deployed KiCI orchestrator.
 2. **Remotely**, if the repo is connected to a KiCI orchestrator via a GitHub App, by calling GitHub's repository-dispatch API: `curl -X POST -H "Authorization: token <PAT>" -H "Accept: application/vnd.github+json" https://api.github.com/repos/<owner>/<repo>/dispatches -d '{"event_type":"hello"}'`. GitHub fans the webhook out to the App, the orchestrator normalizes it into a KiCI `dispatch` event (see `packages/orchestrator/src/providers/github/normalizer.ts`), and the matched workflow runs.
 
 Note that GitHub's `workflow_dispatch` event (the "Run workflow" button / `/actions/workflows/.../dispatches` API) is GitHub-Actions-internal and is **not** delivered to KiCI. The SDK has no `workflowDispatch()` trigger. Only `repository_dispatch` reaches KiCI.
@@ -217,36 +217,18 @@ export default workflow('hello-world', {
 });
 ```
 
-Run it locally, without any orchestrator or agent infrastructure:
+Run it locally, without any orchestrator deployment:
 
 ```bash
 npx kici compile           # regenerate .kici/kici.lock.json
-npx kici run local dispatch
+npx kici run dispatch --local
 ```
 
-`kici run local` compiles the workflow, matches triggers against a simulated `dispatch` event, and executes the matched jobs directly on your machine with DAG-based scheduling. No webhook, no GitHub, no deployed orchestrator involved. See [`kici run local`](https://docs.kici.dev/user/cli-reference/#kici-run-local) for options like `--job`, `--env`, `--json`, and `--junit`.
-
-### Scoping to a single workflow
-
-Because `kici run local dispatch` matches **every** workflow that listens for a `dispatch` event, running it in a repo with several dispatch-triggered workflows will fire all of them. Narrow execution to one with `--workflow <name>`:
-
-```bash
-npx kici run local dispatch --workflow hello-world
-```
-
-`--workflow` is a post-match filter: the workflow still has to have a trigger that matches the event argument. If `hello-world` does not list a `dispatch()` trigger, the command reports `No workflow named "hello-world" matched the event` and exits successfully without running anything.
-
-If you do not want to memorise event args, use the interactive picker instead:
-
-```bash
-npx kici run local --pick
-```
-
-`--pick` (aliased as `-p`) lists every workflow alongside a compact summary of its triggers, lets you select one, and derives a matching event arg from the chosen trigger — so the execution still flows through the normal trigger-matching pipeline and "cannot produce an inconsistent run". Multi-trigger workflows show a second prompt for which trigger to simulate. `--pick` is mutually exclusive with `--workflow`; in a non-TTY shell it prints the workflow list and exits without running anything.
+`kici run dispatch --local` compiles the workflow, matches triggers against a simulated `dispatch` event, and executes the matched jobs on this machine — which joins as an ephemeral agent through the warm local dev plane — with DAG-based scheduling. No webhook, no GitHub, no deployed orchestrator involved. See [`kici run <event> --local`](https://docs.kici.dev/user/cli-reference/#kici-run-event---local) for options like `--env`, `--in-place`, and `--offline`.
 
 ### Unfiltered vs typed `dispatch()`
 
-Leave `dispatch()` unfiltered while you drive it from `kici run local`. The CLI currently simulates a dispatch event with no event type (i.e. `action` is undefined), so a trigger defined as `dispatch({ types: ['deploy', 'rollback'] })` will not match `kici run local dispatch` — the typed form is intended for real `repository_dispatch` deliveries from the orchestrator.
+Leave `dispatch()` unfiltered while you drive it from `kici run <event> --local`. The CLI simulates a dispatch event with no event type (i.e. `action` is undefined), so a trigger defined as `dispatch({ types: ['deploy', 'rollback'] })` will not match `kici run dispatch --local` — the typed form is intended for real `repository_dispatch` deliveries from the orchestrator.
 
 ## Conditional execution with rules
 

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

@@ -10,7 +10,9 @@ The **GitHub App** is KiCI's flagship source. A single App:
 
 1. receives `push`, `pull_request`, and related events from every repo it's installed on,
 2. clones repos with a short-lived installation token (no deploy key to manage),
-3. posts workflow / job / step Check runs back to the pull request (see
+3. posts workflow / job / step Check runs back to the commit — visible on
+   the commit view for a plain `push` and on the **Checks** tab of any pull
+   request that contains it (see
    [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/)).
 
 You don't need an App for every scenario — if you only care about `push`
@@ -347,6 +349,13 @@ driven by the orchestrator's reporting module; no workflow
 configuration is required beyond installing the App with the
 `checks: write` permission.
 
+Check runs are keyed to the head commit SHA, so they surface whether or
+not a pull request exists: after a `push` you see the pass/fail directly
+on the commit (a red ✗ / green ✓ next to the SHA in GitHub's commit list
+and on the commit page), and the same checks roll up into the **Checks**
+tab of any pull request that later includes the commit. A failing run is
+therefore visible in GitHub itself without opening the KiCI dashboard.
+
 For architecture details see
 [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/).
 

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

@@ -169,8 +169,8 @@ function workflow(name: string, options: WorkflowOptions): Workflow;
 | `options.rules`       | `Rule[]`                                                               | no       | Conditions that must pass for execution                                                                                                                     |
 | `options.description` | `string`                                                               | no       | Human-readable description                                                                                                                                  |
 | `options.hashFiles`   | `string[]`                                                             | no       | Extra repo-relative paths or globs mixed into the workflow content hash. Changes invalidate the source cache.                                               |
-| `options.registries`  | `Registry[]`                                                           | no       | Private npm registries the agent authenticates against before `npm install`. Each `tokenSecret` uses qualified `<environment>:<secret>` syntax.             |
-| `options.installEnv`  | `string[]`                                                             | no       | Qualified `<environment>:<secret>` refs projected as env vars onto the install subprocess (used with a customer-committed `.kici/.npmrc`).                  |
+| `options.registries`  | `Registry[]`                                                           | no       | Private npm registries the agent authenticates against before `npm install`. Each `tokenSecret` uses qualified `<context>:<secret>` syntax.                 |
+| `options.installEnv`  | `string[]`                                                             | no       | Qualified `<context>:<secret>` refs projected as env vars onto the install subprocess (used with a customer-committed `.kici/.npmrc`).                      |
 | `options.onCancel`    | `HookInput`                                                            | no       | Runs when the workflow is cancelled                                                                                                                         |
 | `options.cleanup`     | `HookInput`                                                            | no       | Always runs after the workflow (success, failure, or cancel)                                                                                                |
 | `options.onSuccess`   | `HookInput`                                                            | no       | Runs on workflow success                                                                                                                                    |
@@ -721,7 +721,7 @@ step('fetch-token', {
 - **Timeout is per-attempt.** Each attempt gets the step's full `timeout` budget — a timed-out attempt counts as one failed attempt and is retried while attempts remain. The total wall-clock can therefore approach `maxAttempts * (timeout + delay)`, so keep `maxAttempts` and `maxDelayMs` sane (the job-level `timeout` still bounds the whole job).
 - **Retries exhaust before `continueOnError`.** A step with both retries first; only the _final_ failure is then softened to a warning by `continueOnError`.
 
-`retry` works identically under `kici run local` and on a remote agent, and applies to dynamically-generated job steps too. The `retryIf` predicate is an in-memory function: it is honored at execution time but never serialized into the lock file.
+`retry` works identically under `kici run <event> --local` and on a remote agent, and applies to dynamically-generated job steps too. The `retryIf` predicate is an in-memory function: it is honored at execution time but never serialized into the lock file.
 
 > **Retry vs. wait-until-condition.** `retry` re-runs a step that _throws_. To poll until a condition becomes true (a port listening, a `/health` endpoint returning 200, a unit becoming active), use [`waitForStep`](https://docs.kici.dev/user/sdk/wait-for/) instead — it is purpose-built for declarative wait-for-condition with intervals, a timeout, and on-timeout handling.
 
@@ -807,7 +807,7 @@ const deploy = job('deploy', {
 
 **Important:** `needs` must be declared explicitly. Output chaining does not auto-infer dependencies -- you must list job dependencies in `needs` even if you access their outputs via `.result`.
 
-Cross-job output chaining works in both local execution (`kici run local`) and remote pipeline execution. The orchestrator's needs-aware dispatch scheduler guarantees upstream jobs reach a terminal state before downstream jobs dispatch, and upstream outputs are transported to the downstream agent sandbox via the `upstreamJobOutputs` field on `job.dispatch`. See [needs-scheduler](https://docs.kici.dev/architecture/execution/needs-scheduler/) for the full dispatch semantics.
+Cross-job output chaining works in both local execution (`kici run <event> --local`) and remote pipeline execution. The orchestrator's needs-aware dispatch scheduler guarantees upstream jobs reach a terminal state before downstream jobs dispatch, and upstream outputs are transported to the downstream agent sandbox via the `upstreamJobOutputs` field on `job.dispatch`. See [needs-scheduler](https://docs.kici.dev/architecture/execution/needs-scheduler/) for the full dispatch semantics.
 
 ### Job dependencies (`needs`)
 
@@ -1548,7 +1548,7 @@ inside a fan-out job nests its concurrency inside each fan-out child.
 ## Local vs remote execution
 
 Run remotely (the orchestrator + agent), parallel children execute concurrently
-and each surfaces as its own dashboard step. `kici run local` executes the same
+and each surfaces as its own dashboard step. `kici run <event> --local` executes the same
 children in array order in its single-process model — the results are identical,
 only the wall-clock and the live fail-fast cancellation differ. Use a remote run
 to observe the concurrent timeline.
@@ -1688,7 +1688,7 @@ Every variant carries the shared `EventBase` fields — `type`, `action`, `targe
 
 Matrix configurations expand a single job into multiple instances, one per parameter combination. Maximum 256 combinations.
 
-Expansion happens at **dispatch time**: the orchestrator materializes the matrix into N execution jobs — one per combination, each dispatched to its own agent — before any job runs. Each instance receives its combination as `ctx.matrix`. This is identical whether the workflow runs via `kici run local` or remotely through a webhook trigger, and the dashboard groups the N instances under one parent node.
+Expansion happens at **dispatch time**: the orchestrator materializes the matrix into N execution jobs — one per combination, each dispatched to its own agent — before any job runs. Each instance receives its combination as `ctx.matrix`. This is identical whether the workflow runs via `kici run <event> --local` or remotely through a webhook trigger, and the dashboard groups the N instances under one parent node.
 
 ### Static array (single dimension)
 
@@ -1834,7 +1834,7 @@ step('collect', async ({ jobOutputs }) => {
 });
 ```
 
-The downstream job waits for **all** matrix combinations to terminate before it dispatches. A non-matrix upstream keeps the flat outputs shape. The envelope is identical under `kici run local` and the remote path.
+The downstream job waits for **all** matrix combinations to terminate before it dispatches. A non-matrix upstream keeps the flat outputs shape. The envelope is identical under `kici run <event> --local` and the remote path.
 
 ### Matrix type guards
 
@@ -2758,14 +2758,14 @@ verify → view journey, including how to verify a bundle with `kici verify-atte
 
 Workflows access secrets through `ctx.secrets` on `StepContext`. Use `await ctx.secrets.get('KEY')` to retrieve a value (rejects with `SecretNotFoundError` if the key is missing, fail-fast on typos), `ctx.secrets.has('KEY')` for a synchronous existence check, and `await ctx.secrets.expose('KEY')` when you need the value as a `process.env` entry for a child process.
 
-### Declaring the secret environment
+### Declaring the secret context
 
-Each job picks its secret environment via the `environment` option on `job()`. The orchestrator resolves the environment's scoped-secret store at dispatch time, evaluates access rules, and sends the decrypted secrets to the agent:
+Each job picks its secret context via the `context` option on `job()`. The orchestrator resolves the context's scoped-secret store at dispatch time, evaluates access rules, and sends the decrypted secrets to the agent:
 
 ```typescript
 const deploy = job('deploy', {
   runsOn: 'linux',
-  environment: 'production',
+  context: 'production',
   steps: [
     /* ... */
   ],
@@ -2777,11 +2777,11 @@ export default workflow('deploy', {
 });
 ```
 
-`environment` accepts either a static string or an async function `(event) => string | Promise<string>` for dynamic resolution at trigger-evaluation time. The resolved environment's secrets are flattened into `ctx.secrets`.
+`context` accepts either a static string or an async function `(event) => string | Promise<string>` for dynamic resolution at trigger-evaluation time. The resolved context's secrets are flattened into `ctx.secrets`.
 
 ### Accessing secrets (ctx.secrets)
 
-`ctx.secrets` provides flat access to the secrets resolved for the job's environment.
+`ctx.secrets` provides flat access to the secrets resolved for the job's context.
 
 ```typescript
 step('deploy', async ({ secrets }) => {

package/dist/llm-context/llms.txt

@@ -9,11 +9,11 @@ The full markdown bundle of every page indexed here is available at https://docs
 Each bundle below is a self-contained markdown file for one authoring task. Fetch only the one your task needs instead of the full bundle:
 
 - [getting-started](https://docs.kici.dev/llms-getting-started.txt) (25 KB) — Install the SDK, write your first workflow, compile and test locally
-- [patterns](https://docs.kici.dev/llms-patterns.txt) (49 KB) — Copy-paste workflow recipes: triggers, conditionals, matrix, scheduling, integrations
+- [patterns](https://docs.kici.dev/llms-patterns.txt) (48 KB) — Copy-paste workflow recipes: triggers, conditionals, matrix, scheduling, integrations
 - [sdk](https://docs.kici.dev/llms-sdk.txt) (190 KB) — Authoring API: workflow/job/step factories, triggers, rules, matrix, runtime, caching
-- [cli](https://docs.kici.dev/llms-cli.txt) (136 KB) — Running the CLI: compile, test, run local/remote, auth, hooks, lock-file drift
-- [features](https://docs.kici.dev/llms-features.txt) (126 KB) — Workflow features: concurrency, environments, secrets, approvals, provenance, events
-- [providers](https://docs.kici.dev/llms-providers.txt) (36 KB) — Connecting sources: GitHub App, universal-git (Forgejo/Gitea/GitLab), local file://
+- [cli](https://docs.kici.dev/llms-cli.txt) (135 KB) — Running the CLI: compile, test, run local/remote, auth, hooks, lock-file drift
+- [features](https://docs.kici.dev/llms-features.txt) (125 KB) — Workflow features: concurrency, contexts, secrets, approvals, provenance, events
+- [providers](https://docs.kici.dev/llms-providers.txt) (37 KB) — Connecting sources: GitHub App, universal-git (Forgejo/Gitea/GitLab), local file://
 - [architecture](https://docs.kici.dev/llms-architecture.txt) (87 KB) — How the runtime works: three-tier relay model, data flows, configuration
 
 ## Getting started
@@ -61,10 +61,10 @@ Each bundle below is a self-contained markdown file for one authoring task. Fetc
 - [Account and sign-in](https://docs.kici.dev/user/account-and-login/): How your KiCI account relates to sign-in methods, and how to change the way you sign in.
 - [Approval gates](https://docs.kici.dev/user/approvals/): Pause a workflow for human sign-off at step, job, or workflow granularity with approval
 - [Concurrency groups](https://docs.kici.dev/user/concurrency/): Control parallel execution with auto-cancel and queue modes
+- [Contexts](https://docs.kici.dev/user/contexts/): Configure deployment contexts with variables, secrets, and protection rules
 - [Dashboard](https://docs.kici.dev/user/dashboard/): Web UI for monitoring workflow runs, managing sources, secrets, and organization settings.
 - [Dynamic values](https://docs.kici.dev/user/dynamic-values/)
 - [Environment variables](https://docs.kici.dev/user/env-vars/): KICI_* environment variable reference for the CLI
-- [Environments](https://docs.kici.dev/user/environments/): Configure deployment environments with variables, secrets, and protection rules
 - [Event system](https://docs.kici.dev/user/events/): How KiCI's event model works -- event types, the registration model, event matching, and circuit breaker protection
 - [Global workflows](https://docs.kici.dev/user/global-workflows/): Cross-repo workflows that run on events from any repo in the same org
 - [Idempotent steps and check mode](https://docs.kici.dev/user/idempotent-steps/): Declare desired state with a step check facet, then run in apply or --check preview mode

package/dist/local-executor/secret-loader.d.ts

@@ -5,7 +5,7 @@ import type { ParsedSecrets } from '../test-runner/secrets-file.js';
  * Merge order (lowest to highest priority):
  * 1. .kici/.secrets (INI-style, backward compat)
  * 2. .kici/.env.local (dotenv format)
- * 3. .kici/secrets.yaml (YAML with environment scopes, merged flat)
+ * 3. .kici/secrets.yaml (YAML with context scopes, merged flat)
  * 4. --env KEY=VALUE CLI flags
  *
  * Note: process.env is NOT merged here -- it's handled at step-context level.

package/dist/local-plane/orchestrator-process.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Resolve a host address the plane's co-located bare-metal agent can reach for
+ * cache-blob fetches. The orchestrator refuses to hand a scaler a loopback
+ * storage URL (it assumes remote agents), so the plane advertises its first
+ * non-internal IPv4 (still this machine — the agent is co-located). Falls back
+ * to the hostname when no external interface is present.
+ */
+export declare function resolveAgentReachableHost(): string;
+/**
+ * Resolve the built `@kici-dev/orchestrator/standalone` entry the local plane
+ * launches in independent (offline) mode.
+ */
+export declare function resolveStandaloneEntry(): string;
+/**
+ * Resolve the built `@kici-dev/orchestrator/server` entry the local plane
+ * launches in hybrid (Platform-attached) mode.
+ */
+export declare function resolveServerEntry(): string;
+/** Single `/ready` probe against the local orchestrator. */
+export declare function orchestratorReady(port: number): Promise<boolean>;
+/** Options threading the plane's admin token + bare-metal scaler into the boot. */
+export interface SpawnOrchestratorOptions {
+    /** Bootstrap admin token the CLI presents to the plane's admin API. */
+    adminToken: string;
+    /**
+     * Local master secret key (64 hex chars). Enables the orchestrator's secrets
+     * subsystem, which is what gates the admin API routes the CLI drives.
+     */
+    secretKey: string;
+    /** Path to the bare-metal scaler YAML (KICI_SCALER_CONFIG_PATH). */
+    scalerConfigFile: string;
+    /**
+     * Path to the dev-signed identity's EC P-256 private JWK (mode 0600), freshly
+     * generated by the plane. Enables the orchestrator's local OIDC mint +
+     * dev-signed provenance (issuer `kici-local`) in independent mode. Present in
+     * the independent boot; omitted (with `attach`) in the hybrid boot, which
+     * mints via the Platform relay instead.
+     */
+    devIdentityKeyFile?: string;
+    /**
+     * When present, boot the orchestrator in HYBRID mode attached to the Platform
+     * relay instead of independent mode. OIDC + attestation then mint via the
+     * Platform (the local dev signer is never consulted — the orchestrator's
+     * `selectOidcMintRegistration` prefers the relay whenever a Platform
+     * connection exists).
+     */
+    attach?: {
+        /** Orchestrator KICI_PLATFORM_URL — a ws(s)://…/ws relay URL. */
+        platformWsUrl: string;
+        /** Org-scoped orchestrator key (kici_ok_…) presented on WS auth. */
+        platformToken: string;
+    };
+}
+/**
+ * Spawn the orchestrator's standalone entry in independent mode against the
+ * local Postgres, detached, with stdout/stderr redirected to the plane log.
+ * Boots with a bootstrap admin token (so the CLI can drive the admin API) and a
+ * bare-metal scaler (so a dispatched job auto-spawns an ephemeral agent). Waits
+ * for `GET /ready` to report warm, then returns the child pid + port.
+ */
+export declare function spawnOrchestrator(databaseUrl: string, opts: SpawnOrchestratorOptions): Promise<{
+    pid: number;
+    port: number;
+}>;
+//# sourceMappingURL=orchestrator-process.d.ts.map

package/dist/local-plane/orchestrator-process.js

@@ -0,0 +1,115 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { planePaths, planePorts } from "./paths.js";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+import os from "node:os";
+//#region src/local-plane/orchestrator-process.ts
+/**
+* Resolve a host address the plane's co-located bare-metal agent can reach for
+* cache-blob fetches. The orchestrator refuses to hand a scaler a loopback
+* storage URL (it assumes remote agents), so the plane advertises its first
+* non-internal IPv4 (still this machine — the agent is co-located). Falls back
+* to the hostname when no external interface is present.
+*/
+function resolveAgentReachableHost() {
+	for (const addrs of Object.values(os.networkInterfaces())) for (const a of addrs ?? []) if (a.family === "IPv4" && !a.internal) return a.address;
+	return os.hostname();
+}
+/**
+* Resolve the built `@kici-dev/orchestrator/standalone` entry the local plane
+* launches in independent (offline) mode.
+*/
+function resolveStandaloneEntry() {
+	return createRequire(import.meta.url).resolve("@kici-dev/orchestrator/standalone");
+}
+/**
+* Resolve the built `@kici-dev/orchestrator/server` entry the local plane
+* launches in hybrid (Platform-attached) mode.
+*/
+function resolveServerEntry() {
+	return createRequire(import.meta.url).resolve("@kici-dev/orchestrator/server");
+}
+/** Single `/ready` probe against the local orchestrator. */
+async function orchestratorReady(port) {
+	try {
+		return (await fetch(`http://127.0.0.1:${port}/ready`)).status === 200;
+	} catch {
+		return false;
+	}
+}
+/**
+* Spawn the orchestrator's standalone entry in independent mode against the
+* local Postgres, detached, with stdout/stderr redirected to the plane log.
+* Boots with a bootstrap admin token (so the CLI can drive the admin API) and a
+* bare-metal scaler (so a dispatched job auto-spawns an ephemeral agent). Waits
+* for `GET /ready` to report warm, then returns the child pid + port.
+*/
+async function spawnOrchestrator(databaseUrl, opts) {
+	const { orchestrator: port } = planePorts();
+	const { logFile, root, cacheDir } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	fs.mkdirSync(cacheDir, { recursive: true });
+	const out = fs.openSync(logFile, "a");
+	const baseEnv = {};
+	for (const [key, value] of Object.entries(process.env)) if (!key.startsWith("KICI_")) baseEnv[key] = value;
+	const commonEnv = {
+		...baseEnv,
+		KICI_PORT: String(port),
+		KICI_DATABASE_URL: databaseUrl,
+		KICI_AGENT_AUTH: "none",
+		KICI_AUTO_MIGRATE: "true",
+		KICI_DATA_DIR: root,
+		KICI_BOOTSTRAP_ADMIN_TOKEN: opts.adminToken,
+		KICI_SECRET_KEY: opts.secretKey,
+		KICI_SCALER_CONFIG_PATH: opts.scalerConfigFile,
+		KICI_WEBHOOK_PUBLIC_URL: `http://127.0.0.1:${port}`,
+		KICI_STORAGE_TYPE: "filesystem",
+		KICI_STORAGE_FS_PATH: cacheDir,
+		KICI_STORAGE_FS_BASE_URL: `http://${resolveAgentReachableHost()}:${port}`
+	};
+	let entry;
+	let modeEnv;
+	if (opts.attach) {
+		entry = resolveServerEntry();
+		modeEnv = {
+			KICI_MODE: "hybrid",
+			KICI_PLATFORM_URL: opts.attach.platformWsUrl,
+			KICI_PLATFORM_TOKEN: opts.attach.platformToken
+		};
+	} else {
+		entry = resolveStandaloneEntry();
+		modeEnv = {
+			KICI_MODE: "independent",
+			KICI_INDEPENDENT_SECRETS: "true",
+			KICI_INDEPENDENT_IDENTITY: "true",
+			KICI_DEV_IDENTITY_KEY_FILE: opts.devIdentityKeyFile,
+			KICI_PROVENANCE_ISSUER: "kici-local"
+		};
+	}
+	const child = spawn(process.execPath, [entry], {
+		detached: true,
+		stdio: [
+			"ignore",
+			out,
+			out
+		],
+		env: {
+			...commonEnv,
+			...modeEnv
+		}
+	});
+	child.unref();
+	for (let i = 0; i < 120; i++) {
+		if (await orchestratorReady(port)) return {
+			pid: child.pid,
+			port
+		};
+		await new Promise((r) => setTimeout(r, 500));
+	}
+	throw new Error("local orchestrator did not become ready");
+}
+//#endregion
+export { orchestratorReady, resolveAgentReachableHost, resolveServerEntry, resolveStandaloneEntry, spawnOrchestrator };
+
+//# sourceMappingURL=orchestrator-process.js.map

package/dist/local-plane/paths.d.ts

@@ -0,0 +1,39 @@
+/**
+ * On-disk layout version of the local dev plane. Bumped when the state-dir
+ * structure changes incompatibly, so a stamped plane from an older layout is
+ * recreated rather than reused.
+ */
+export declare const PLANE_STAMP_VERSION = 3;
+/**
+ * Root directory of the local dev plane's state, following the same
+ * `KICI_CONFIG_DIR` → `~/.kici` convention the rest of the CLI uses.
+ */
+export declare function planeRoot(): string;
+/**
+ * Absolute paths for every artefact the plane persists under its state root.
+ */
+export declare function planePaths(): {
+    root: string;
+    pgData: string;
+    pidfile: string;
+    stampFile: string;
+    logFile: string;
+    socketDir: string;
+    adminTokenFile: string;
+    platformTokenFile: string;
+    attachmentFile: string;
+    secretKeyFile: string;
+    scalerConfigFile: string;
+    agentWrapperFile: string;
+    devIdentityDir: string;
+    cacheDir: string;
+};
+/**
+ * Fixed localhost ports for the plane's orchestrator (HTTP+WS) and Postgres.
+ * Overridable via `KICI_LOCAL_ORCH_PORT` / `KICI_LOCAL_PG_PORT`.
+ */
+export declare function planePorts(): {
+    orchestrator: number;
+    postgres: number;
+};
+//# sourceMappingURL=paths.d.ts.map

package/dist/local-plane/paths.js

@@ -0,0 +1,54 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import path from "node:path";
+import os from "node:os";
+//#region src/local-plane/paths.ts
+/**
+* On-disk layout version of the local dev plane. Bumped when the state-dir
+* structure changes incompatibly, so a stamped plane from an older layout is
+* recreated rather than reused.
+*/
+const PLANE_STAMP_VERSION = 3;
+/**
+* Root directory of the local dev plane's state, following the same
+* `KICI_CONFIG_DIR` → `~/.kici` convention the rest of the CLI uses.
+*/
+function planeRoot() {
+	const base = process.env.KICI_CONFIG_DIR ?? path.join(os.homedir(), ".kici");
+	return path.join(base, "local");
+}
+/**
+* Absolute paths for every artefact the plane persists under its state root.
+*/
+function planePaths() {
+	const root = planeRoot();
+	return {
+		root,
+		pgData: path.join(root, "pgdata"),
+		pidfile: path.join(root, "plane.pid"),
+		stampFile: path.join(root, "stamp.json"),
+		logFile: path.join(root, "orchestrator.log"),
+		socketDir: path.join(root, "sock"),
+		adminTokenFile: path.join(root, "admin-token"),
+		platformTokenFile: path.join(root, "platform-token"),
+		attachmentFile: path.join(root, "attachment.json"),
+		secretKeyFile: path.join(root, "secret-key"),
+		scalerConfigFile: path.join(root, "scaler.yaml"),
+		agentWrapperFile: path.join(root, "agent-wrapper.sh"),
+		devIdentityDir: path.join(root, "dev-identity"),
+		cacheDir: path.join(root, "cache")
+	};
+}
+/**
+* Fixed localhost ports for the plane's orchestrator (HTTP+WS) and Postgres.
+* Overridable via `KICI_LOCAL_ORCH_PORT` / `KICI_LOCAL_PG_PORT`.
+*/
+function planePorts() {
+	return {
+		orchestrator: Number(process.env.KICI_LOCAL_ORCH_PORT ?? 4319),
+		postgres: Number(process.env.KICI_LOCAL_PG_PORT ?? 45432)
+	};
+}
+//#endregion
+export { PLANE_STAMP_VERSION, planePaths, planePorts, planeRoot };
+
+//# sourceMappingURL=paths.js.map