@kici-dev/compiler 0.1.26 → 0.2.0

package/dist/local-plane/run-follow.js

@@ -0,0 +1,151 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { ExecutionJobStatus, ExecutionRunStatus, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES } from "@kici-dev/engine";
+import { AdminApiClient } from "@kici-dev/orchestrator";
+//#region src/local-plane/run-follow.ts
+/**
+* Follow an offline routed run against the local plane by polling the
+* orchestrator admin API (no SSE in independent mode). Streams step log lines as
+* they arrive and resolves when the run reaches a terminal state.
+*/
+/**
+* Job states that mean the job did NOT succeed (failed / stale / cancelled /
+* dropped / unroutable). Read only by the anti-false-green guard below, so a
+* missing member lets a lagging `success` run header be reported verbatim even
+* though a job settled badly.
+*/
+const FAILED_JOB_STATES = /* @__PURE__ */ new Set([
+	ExecutionJobStatus.enum.failed,
+	ExecutionJobStatus.enum.timed_out_stale,
+	ExecutionJobStatus.enum.cancelled,
+	ExecutionJobStatus.enum.drift_dropped,
+	ExecutionJobStatus.enum.unroutable
+]);
+/** Job states in which no agent has claimed the job yet. */
+const UNCLAIMED_JOB_STATES = /* @__PURE__ */ new Set([ExecutionJobStatus.enum.pending, ExecutionJobStatus.enum.queued]);
+/**
+* How often the acceptance check re-fetches jobs. Deliberately far coarser than
+* the poll interval: at 750 ms a two-minute window would cost ~160 extra admin
+* requests to answer a question that changes once.
+*/
+const ACCEPTANCE_CHECK_INTERVAL_MS = 5e3;
+/** Default window for an agent to claim the run before the follow gives up. */
+const DEFAULT_ACCEPTANCE_TIMEOUT_MS = 12e4;
+/**
+* Resolve the acceptance window, falling back to the default for any value that
+* is not a positive number of milliseconds.
+*
+* A malformed override must never reach the deadline arithmetic: `Number('')`
+* is `0` (every run fails instantly) and `Number('2 min')` is `NaN`, which makes
+* `now > deadline` permanently false and silently restores the 900 s hang this
+* window exists to prevent. Both failure modes are worse than ignoring a typo.
+*/
+function resolveAcceptanceTimeoutMs(explicitMs, raw) {
+	if (explicitMs !== void 0) return explicitMs;
+	if (raw === void 0) return DEFAULT_ACCEPTANCE_TIMEOUT_MS;
+	const parsed = Number(raw);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_ACCEPTANCE_TIMEOUT_MS;
+}
+/** Poll a run to completion, streaming step logs. */
+async function followRun(planeUrl, adminToken, runId, opts = {}) {
+	const client = opts.client ?? new AdminApiClient(planeUrl, adminToken);
+	const pollIntervalMs = opts.pollIntervalMs ?? 750;
+	const idleTimeoutMs = opts.idleTimeoutMs ?? opts.timeoutMs ?? 9e5;
+	const maxTotalMs = opts.maxTotalMs ?? 72e5;
+	const acceptanceTimeoutMs = resolveAcceptanceTimeoutMs(opts.acceptanceTimeoutMs, process.env.KICI_LOCAL_ACCEPTANCE_TIMEOUT_MS);
+	const cursors = /* @__PURE__ */ new Map();
+	const stream = !opts.quiet && opts.onLine ? opts.onLine : void 0;
+	const startedAt = Date.now();
+	let lastProgressAt = startedAt;
+	let lastStatus = "";
+	let accepted = false;
+	let acceptanceDeadline = startedAt + acceptanceTimeoutMs;
+	let lastAcceptanceCheck = 0;
+	for (;;) {
+		const now = Date.now();
+		if (now - lastProgressAt > idleTimeoutMs) throw new Error(`offline run: follow timed out (no progress for ${idleTimeoutMs}ms) for run ${runId}`);
+		if (now - startedAt > maxTotalMs) throw new Error(`offline run: follow exceeded its max window (${maxTotalMs}ms) for run ${runId}`);
+		const { run } = await client.get(`/api/v1/admin/runs/${runId}`);
+		if (!accepted && !TERMINAL_RUN_STATES.has(run.status)) {
+			if (run.status === ExecutionRunStatus.enum.held) acceptanceDeadline = now + acceptanceTimeoutMs;
+			else if (now - lastAcceptanceCheck >= ACCEPTANCE_CHECK_INTERVAL_MS) {
+				lastAcceptanceCheck = now;
+				const claimedJobs = await fetchJobs(client, runId);
+				accepted = claimedJobs.length > 0 && claimedJobs.some((j) => !UNCLAIMED_JOB_STATES.has(j.status));
+			}
+			if (!accepted && now > acceptanceDeadline) {
+				const seconds = Math.round(acceptanceTimeoutMs / 1e3);
+				throw new Error(`offline run: no agent picked up this run within ${seconds}s — no scaler label set matched the job's runsOn, or the agent failed to start.` + (opts.hintLogPath ? ` Plane log: ${opts.hintLogPath}` : ""));
+			}
+		}
+		let progressed = false;
+		if (run.status !== lastStatus) {
+			lastStatus = run.status;
+			progressed = true;
+		}
+		if (stream) {
+			if (await drainLogs(client, runId, cursors, stream) > 0) progressed = true;
+		}
+		if (progressed) lastProgressAt = now;
+		if (TERMINAL_RUN_STATES.has(run.status)) {
+			const jobs = await fetchJobs(client, runId);
+			const allTerminal = jobs.length > 0 && jobs.every((j) => TERMINAL_JOB_STATES.has(j.status));
+			const anyFailed = jobs.some((j) => FAILED_JOB_STATES.has(j.status));
+			if (allTerminal && !(run.status === "success" && anyFailed)) {
+				if (stream) await drainLogs(client, runId, cursors, stream);
+				return {
+					runId,
+					status: run.status,
+					jobs
+				};
+			}
+		}
+		await sleep(pollIntervalMs);
+	}
+}
+/** Fetch the run's jobs mapped to the summary shape. */
+async function fetchJobs(client, runId) {
+	const { jobs } = await client.get(`/api/v1/admin/runs/${runId}/jobs`);
+	return jobs.map((j) => ({
+		name: j.jobName,
+		status: j.status,
+		durationMs: j.durationMs ?? void 0
+	}));
+}
+/**
+* Stream any new step-log lines. Best-effort: a per-step fetch error never
+* aborts the follow (logs are observability, not the terminal signal).
+*/
+async function drainLogs(client, runId, cursors, onLine) {
+	let emitted = 0;
+	let jobs;
+	try {
+		jobs = (await client.get(`/api/v1/admin/runs/${runId}/jobs?includeSteps=true`)).jobs;
+	} catch {
+		return emitted;
+	}
+	for (const job of jobs) for (const step of job.steps ?? []) {
+		const key = `${job.jobId}:${step.stepIndex}`;
+		try {
+			let cursor = cursors.get(key);
+			for (;;) {
+				const qs = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
+				const page = await client.get(`/api/v1/admin/runs/${runId}/jobs/${job.jobId}/steps/${step.stepIndex}/logs${qs}`);
+				for (const l of page.lines) {
+					onLine(l.value);
+					emitted++;
+				}
+				cursor = page.nextCursor ?? String(page.totalLines);
+				cursors.set(key, cursor);
+				if (!page.nextCursor) break;
+			}
+		} catch {}
+	}
+	return emitted;
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+//#endregion
+export { followRun, resolveAcceptanceTimeoutMs };
+
+//# sourceMappingURL=run-follow.js.map

package/dist/local-plane/scaler-config.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Bare-metal scaler configuration for the local dev plane.
+ *
+ * A dispatched job needs an agent to run it. The plane orchestrator boots with
+ * a single bare-metal scaler pointed at a label set matching the default
+ * `runsOn` (`default`), so an offline `kici run --local` dispatch auto-spawns an
+ * ephemeral, one-job-then-exit agent on this machine. The spawned binary is a
+ * small executable wrapper that execs `node <@kici-dev/agent server entry>` —
+ * mirroring the shape proven by the `local-file-source` E2E, and avoiding a
+ * dependency on the (non-executable) shipped `kici-agent` script.
+ */
+/** Resolve the built `@kici-dev/agent` server entry the bare-metal scaler runs. */
+export declare function resolveAgentBinary(): string;
+/**
+ * Write the executable wrapper the bare-metal scaler spawns. The scaler invokes
+ * `spawn(binaryPath, [])` directly, so the target must be an executable file;
+ * the shipped agent entry is a plain Node module without an exec bit, so this
+ * wrapper bridges the gap. Returns the wrapper path.
+ */
+export declare function writeAgentWrapper(): string;
+/**
+ * The non-reserved routing label a `kici run --local --trusted` run appends to
+ * every job's `runsOn` so the dispatch lands on the plane's trusted label set.
+ * `self-hosted` (not a `kici:`-prefixed reserved label) is also the `runsOn` the
+ * CI deploy/CDN workflows already declare, so those route to the trusted profile
+ * on this plane by construction.
+ */
+export declare const TRUSTED_ROUTING_LABEL = "self-hosted";
+/**
+ * The non-reserved routing label a `kici run --local --trusted --in-place` run
+ * appends (alongside `self-hosted`) so the dispatch lands on the plane's trusted
+ * **in-place** label set — the agent runs the operator's real working tree
+ * directly (no clone). This is the profile KiCI's own routed `deploy:stg` uses.
+ */
+export declare const IN_PLACE_ROUTING_LABEL = "in-place";
+/**
+ * Write the plane's bare-metal scaler YAML and return its path. TWO coexisting
+ * bare-metal scalers spawn the agent wrapper against the plane orchestrator's
+ * localhost WS endpoint — a **sandboxed** pool and a `self-hosted`-**tainted**
+ * TRUSTED pool:
+ *
+ * - `kici-local-bare-metal` (sandboxed) — one `default` label set, no taint. The
+ *   credential-isolated profile a normal `kici run --local` dispatch (jobs with
+ *   `runsOn: ['default']` or none) lands on. Its agents inherit no
+ *   `mandatoryLabels`, so a bare `default` job routes here.
+ * - `kici-local-bare-metal-trusted` (TRUSTED) — carries `mandatoryLabels:
+ *   ['self-hosted']`, so ONLY a job that explicitly requests `self-hosted`
+ *   (i.e. a `kici run --local --trusted` run, whose lock patch appends the
+ *   `self-hosted` routing label, or a `runsOn: self-hosted` workflow) is ever
+ *   routed to it — at BOTH the scaler spawn matcher AND the orchestrator's
+ *   agent-registry dispatch gate. Two label sets:
+ *     - `default` + `self-hosted` — the trusted fleet profile
+ *       (`KICI_TRUSTED_ENV=true`, bwrap off): steps run with the ambient host
+ *       env passed through, minus the agent's own KiCI identity secrets.
+ *     - `default` + `self-hosted` + `in-place` — the trusted **in-place**
+ *       profile (adds `KICI_IN_PLACE=true`) a `kici run --local --trusted
+ *       --in-place` run lands on: same trusted env, but the agent uses the
+ *       operator's real working tree directly (no clone) — the profile KiCI's
+ *       own routed `deploy:stg` uses.
+ *
+ * The `self-hosted` taint is the isolation guarantee: without it, an idle
+ * trusted agent (spawned for an earlier `--trusted` run and lingering for
+ * follow-up jobs) would satisfy the agent-registry's subset match for a plain
+ * `default` job and leak the ambient host env into a sandboxed run. The taint
+ * closes that at the dispatch layer, not just the spawn heuristic.
+ */
+export declare function writeScalerConfig(orchestratorPort: number): string;
+//# sourceMappingURL=scaler-config.d.ts.map

package/dist/local-plane/scaler-config.js

@@ -0,0 +1,132 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { planePaths } from "./paths.js";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import { stringify } from "yaml";
+//#region src/local-plane/scaler-config.ts
+/**
+* Bare-metal scaler configuration for the local dev plane.
+*
+* A dispatched job needs an agent to run it. The plane orchestrator boots with
+* a single bare-metal scaler pointed at a label set matching the default
+* `runsOn` (`default`), so an offline `kici run --local` dispatch auto-spawns an
+* ephemeral, one-job-then-exit agent on this machine. The spawned binary is a
+* small executable wrapper that execs `node <@kici-dev/agent server entry>` —
+* mirroring the shape proven by the `local-file-source` E2E, and avoiding a
+* dependency on the (non-executable) shipped `kici-agent` script.
+*/
+/** Resolve the built `@kici-dev/agent` server entry the bare-metal scaler runs. */
+function resolveAgentBinary() {
+	return createRequire(import.meta.url).resolve("@kici-dev/agent/server");
+}
+/**
+* Write the executable wrapper the bare-metal scaler spawns. The scaler invokes
+* `spawn(binaryPath, [])` directly, so the target must be an executable file;
+* the shipped agent entry is a plain Node module without an exec bit, so this
+* wrapper bridges the gap. Returns the wrapper path.
+*/
+function writeAgentWrapper() {
+	const { agentWrapperFile, root } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	const server = resolveAgentBinary();
+	fs.writeFileSync(agentWrapperFile, `#!/usr/bin/env bash\nexec node ${JSON.stringify(server)} "$@"\n`);
+	fs.chmodSync(agentWrapperFile, 493);
+	return agentWrapperFile;
+}
+/**
+* The non-reserved routing label a `kici run --local --trusted` run appends to
+* every job's `runsOn` so the dispatch lands on the plane's trusted label set.
+* `self-hosted` (not a `kici:`-prefixed reserved label) is also the `runsOn` the
+* CI deploy/CDN workflows already declare, so those route to the trusted profile
+* on this plane by construction.
+*/
+const TRUSTED_ROUTING_LABEL = "self-hosted";
+/**
+* The non-reserved routing label a `kici run --local --trusted --in-place` run
+* appends (alongside `self-hosted`) so the dispatch lands on the plane's trusted
+* **in-place** label set — the agent runs the operator's real working tree
+* directly (no clone). This is the profile KiCI's own routed `deploy:stg` uses.
+*/
+const IN_PLACE_ROUTING_LABEL = "in-place";
+/**
+* Write the plane's bare-metal scaler YAML and return its path. TWO coexisting
+* bare-metal scalers spawn the agent wrapper against the plane orchestrator's
+* localhost WS endpoint — a **sandboxed** pool and a `self-hosted`-**tainted**
+* TRUSTED pool:
+*
+* - `kici-local-bare-metal` (sandboxed) — one `default` label set, no taint. The
+*   credential-isolated profile a normal `kici run --local` dispatch (jobs with
+*   `runsOn: ['default']` or none) lands on. Its agents inherit no
+*   `mandatoryLabels`, so a bare `default` job routes here.
+* - `kici-local-bare-metal-trusted` (TRUSTED) — carries `mandatoryLabels:
+*   ['self-hosted']`, so ONLY a job that explicitly requests `self-hosted`
+*   (i.e. a `kici run --local --trusted` run, whose lock patch appends the
+*   `self-hosted` routing label, or a `runsOn: self-hosted` workflow) is ever
+*   routed to it — at BOTH the scaler spawn matcher AND the orchestrator's
+*   agent-registry dispatch gate. Two label sets:
+*     - `default` + `self-hosted` — the trusted fleet profile
+*       (`KICI_TRUSTED_ENV=true`, bwrap off): steps run with the ambient host
+*       env passed through, minus the agent's own KiCI identity secrets.
+*     - `default` + `self-hosted` + `in-place` — the trusted **in-place**
+*       profile (adds `KICI_IN_PLACE=true`) a `kici run --local --trusted
+*       --in-place` run lands on: same trusted env, but the agent uses the
+*       operator's real working tree directly (no clone) — the profile KiCI's
+*       own routed `deploy:stg` uses.
+*
+* The `self-hosted` taint is the isolation guarantee: without it, an idle
+* trusted agent (spawned for an earlier `--trusted` run and lingering for
+* follow-up jobs) would satisfy the agent-registry's subset match for a plain
+* `default` job and leak the ambient host env into a sandboxed run. The taint
+* closes that at the dispatch layer, not just the spawn heuristic.
+*/
+function writeScalerConfig(orchestratorPort) {
+	const { scalerConfigFile, root } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	const binaryPath = writeAgentWrapper();
+	const orchestratorUrl = `ws://127.0.0.1:${orchestratorPort}/ws`;
+	const yaml = stringify({
+		version: 1,
+		scalers: [{
+			name: "kici-local-bare-metal",
+			type: "bare-metal",
+			maxAgents: 10,
+			orchestratorUrl,
+			labelSets: [{
+				labels: ["default"],
+				binaryPath
+			}]
+		}, {
+			name: "kici-local-bare-metal-trusted",
+			type: "bare-metal",
+			maxAgents: 10,
+			orchestratorUrl,
+			mandatoryLabels: [TRUSTED_ROUTING_LABEL],
+			labelSets: [{
+				labels: ["default", TRUSTED_ROUTING_LABEL],
+				binaryPath,
+				env: {
+					KICI_TRUSTED_ENV: "true",
+					KICI_SANDBOX: "false"
+				}
+			}, {
+				labels: [
+					"default",
+					TRUSTED_ROUTING_LABEL,
+					IN_PLACE_ROUTING_LABEL
+				],
+				binaryPath,
+				env: {
+					KICI_TRUSTED_ENV: "true",
+					KICI_SANDBOX: "false",
+					KICI_IN_PLACE: "true"
+				}
+			}]
+		}]
+	});
+	fs.writeFileSync(scalerConfigFile, yaml);
+	return scalerConfigFile;
+}
+//#endregion
+export { IN_PLACE_ROUTING_LABEL, TRUSTED_ROUTING_LABEL, resolveAgentBinary, writeAgentWrapper, writeScalerConfig };
+
+//# sourceMappingURL=scaler-config.js.map

package/dist/local-plane/secret-seed.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Seed a project's local `secrets.yaml` (and `.kici/.secrets` INI) contexts into
+ * the local dev plane's real `scoped_secrets` store, preserving context/scope
+ * structure so the plane's real `SecretResolver` honors scoping at dispatch —
+ * the routed local run resolves scoped secrets through the plane's real
+ * resolver rather than a flat merge.
+ *
+ * Local secret files are READ-ONLY here: values are only READ and transit into
+ * the local plane's Postgres via the admin secret API. Nothing is written back
+ * to a secret file, and nothing leaves this machine (the plane is local).
+ *
+ * Scope model: each `secrets.yaml` top-level key is a context name. The seeder
+ * creates a context of that name, binds it to a scope pattern equal to the
+ * context name, and stores each secret at that scope. So a workflow job bound to
+ * context `production` resolves `production`-scoped secrets through the resolver.
+ */
+/** Minimal AdminApiClient surface the seeder needs (for test injection). */
+export interface SecretSeedClient {
+    createContext(data: {
+        orgId: string;
+        name: string;
+        allowLocalExecution?: boolean;
+    }): Promise<{
+        envId: string;
+        created: boolean;
+    }>;
+    bindContext(data: {
+        orgId: string;
+        name: string;
+        scopePattern: string;
+        hostPattern?: string;
+    }): Promise<unknown>;
+    setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
+}
+/** Result of a seed run: the contexts seeded and how many secret keys landed. */
+export interface SeededSecrets {
+    contexts: string[];
+    secretCount: number;
+}
+/**
+ * Collect the per-context secrets from a project's `.kici/` directory,
+ * preserving context structure. Reads `.kici/.secrets` (INI sections) and
+ * `.kici/secrets.yaml` (top-level contexts). The yaml layer wins on key
+ * collisions within a context. Flat (context-less) secrets are ignored here —
+ * a routed job only resolves secrets for the contexts it binds.
+ */
+export declare function loadLocalSecretContexts(kiciDir: string): Promise<Record<string, Record<string, string>>>;
+/**
+ * Seed the local plane's `scoped_secrets` store from a project's `secrets.yaml`
+ * / `.secrets` contexts. Idempotent: `createContext` upserts, `bind` is a no-op
+ * when the scope is already bound, and `setSecret` overwrites in place. Returns
+ * the contexts + secret-key count seeded (never the values).
+ */
+export declare function seedLocalSecrets(planeUrl: string, adminToken: string, opts: {
+    orgId: string;
+    kiciDir: string;
+    client?: SecretSeedClient;
+}): Promise<SeededSecrets>;
+//# sourceMappingURL=secret-seed.d.ts.map

package/dist/local-plane/secret-seed.js

@@ -0,0 +1,112 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { parseSecretsFile } from "../test-runner/secrets-file.js";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+import { AdminApiClient } from "@kici-dev/orchestrator";
+//#region src/local-plane/secret-seed.ts
+/**
+* Seed a project's local `secrets.yaml` (and `.kici/.secrets` INI) contexts into
+* the local dev plane's real `scoped_secrets` store, preserving context/scope
+* structure so the plane's real `SecretResolver` honors scoping at dispatch —
+* the routed local run resolves scoped secrets through the plane's real
+* resolver rather than a flat merge.
+*
+* Local secret files are READ-ONLY here: values are only READ and transit into
+* the local plane's Postgres via the admin secret API. Nothing is written back
+* to a secret file, and nothing leaves this machine (the plane is local).
+*
+* Scope model: each `secrets.yaml` top-level key is a context name. The seeder
+* creates a context of that name, binds it to a scope pattern equal to the
+* context name, and stores each secret at that scope. So a workflow job bound to
+* context `production` resolves `production`-scoped secrets through the resolver.
+*/
+/**
+* Read a file, returning null when it does not exist.
+*/
+async function readFileOrNull(filePath) {
+	try {
+		return await readFile(filePath, "utf-8");
+	} catch (err) {
+		if (err instanceof Error && "code" in err && err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+/**
+* Parse `secrets.yaml`, PRESERVING its top-level context structure (a flat merge
+* would collapse the contexts). Top-level keys are context names; values are
+* key→value maps. Non-scalar leaf values are stringified.
+*/
+function parseSecretsYamlContexts(content) {
+	const parsed = parse(content);
+	if (!parsed || typeof parsed !== "object") return {};
+	const out = {};
+	for (const [contextName, contextSecrets] of Object.entries(parsed)) if (contextSecrets && typeof contextSecrets === "object" && !Array.isArray(contextSecrets)) {
+		const map = {};
+		for (const [key, value] of Object.entries(contextSecrets)) if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") map[key] = String(value);
+		if (Object.keys(map).length > 0) out[contextName] = map;
+	}
+	return out;
+}
+/**
+* Collect the per-context secrets from a project's `.kici/` directory,
+* preserving context structure. Reads `.kici/.secrets` (INI sections) and
+* `.kici/secrets.yaml` (top-level contexts). The yaml layer wins on key
+* collisions within a context. Flat (context-less) secrets are ignored here —
+* a routed job only resolves secrets for the contexts it binds.
+*/
+async function loadLocalSecretContexts(kiciDir) {
+	const contexts = {};
+	const iniContent = await readFileOrNull(path.join(kiciDir, ".secrets"));
+	if (iniContent !== null) {
+		const parsed = parseSecretsFile(iniContent);
+		for (const [ctx, vals] of Object.entries(parsed.contexts)) contexts[ctx] = {
+			...contexts[ctx] ?? {},
+			...vals
+		};
+	}
+	const yamlContent = await readFileOrNull(path.join(kiciDir, "secrets.yaml"));
+	if (yamlContent !== null) for (const [ctx, vals] of Object.entries(parseSecretsYamlContexts(yamlContent))) contexts[ctx] = {
+		...contexts[ctx] ?? {},
+		...vals
+	};
+	return contexts;
+}
+/**
+* Seed the local plane's `scoped_secrets` store from a project's `secrets.yaml`
+* / `.secrets` contexts. Idempotent: `createContext` upserts, `bind` is a no-op
+* when the scope is already bound, and `setSecret` overwrites in place. Returns
+* the contexts + secret-key count seeded (never the values).
+*/
+async function seedLocalSecrets(planeUrl, adminToken, opts) {
+	const client = opts.client ?? new AdminApiClient(planeUrl, adminToken);
+	const contexts = await loadLocalSecretContexts(opts.kiciDir);
+	const seeded = [];
+	let secretCount = 0;
+	for (const [contextName, secrets] of Object.entries(contexts)) {
+		await client.createContext({
+			orgId: opts.orgId,
+			name: contextName,
+			allowLocalExecution: true
+		});
+		await client.bindContext({
+			orgId: opts.orgId,
+			name: contextName,
+			scopePattern: contextName,
+			hostPattern: "**"
+		});
+		for (const [key, value] of Object.entries(secrets)) {
+			await client.setSecret(opts.orgId, contextName, key, value);
+			secretCount++;
+		}
+		seeded.push(contextName);
+	}
+	return {
+		contexts: seeded,
+		secretCount
+	};
+}
+//#endregion
+export { loadLocalSecretContexts, seedLocalSecrets };
+
+//# sourceMappingURL=secret-seed.js.map

package/dist/local-plane/source-provider.d.ts

@@ -0,0 +1,43 @@
+/**
+ * LocalSourceProvider — resolve the workdir a `kici run --local` dispatch
+ * registers as a `file://` source for the plane.
+ *
+ * The plane orchestrator's local provider fetches the lock from
+ * `<repoBasePath>/.kici/kici.lock.json` and the ephemeral agent clones
+ * `file://<repoBasePath>` at a committed sha. So the resolved workdir must be a
+ * git repo whose HEAD carries the workflow + lock the run should execute.
+ *
+ * Two profiles:
+ * - **default (isolated):** an isolated tmp clone at HEAD with the local overlay
+ *   (dirty + untracked files) applied and committed onto a `kici-local` branch,
+ *   so the clone-by-sha the agent performs sees uncommitted work without
+ *   touching the developer's tree.
+ * - **`--in-place`:** the repo root directly (ambient state, the profile the CI
+ *   deploy jobs use). Cleanup is a no-op.
+ */
+/** The `kici-local` branch the isolated profile commits its overlay onto. */
+export declare const LOCAL_RUN_BRANCH = "kici-local";
+/** A resolved workdir plus the git coordinates the plane trigger needs. */
+export interface ResolvedWorkdir {
+    /** Absolute path registered as the local source `repoBasePath`. */
+    dir: string;
+    /** Git ref the synthetic push carries (`refs/heads/<branch>`). */
+    ref: string;
+    /** Committed HEAD sha the agent clones + checks out. */
+    sha: string;
+    /** Branch short name (matched by the workflow's push filter). */
+    branch: string;
+    /** Remove the tmp workdir (no-op for `--in-place`). */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Resolve the workdir for an offline routed run.
+ *
+ * @param opts.inPlace - Use the repo root directly instead of an isolated clone.
+ * @param opts.repoRoot - The developer's repo root.
+ */
+export declare function resolveWorkdir(opts: {
+    inPlace: boolean;
+    repoRoot: string;
+}): Promise<ResolvedWorkdir>;
+//# sourceMappingURL=source-provider.d.ts.map