@kici-dev/compiler 0.1.26 → 0.2.0

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

@@ -0,0 +1,76 @@
+/**
+ * Seed the local `file://` source the plane dispatches an offline routed run
+ * through. Idempotent: a stable `kici-local` source is created once and its
+ * `repoBasePath` is re-pointed at the current workdir on every run (the isolated
+ * profile materializes a fresh tmp clone each time). The org is the independent
+ * orchestrator's `__default__` sentinel — the orchestrator DB has no org table,
+ * so seeding an org is just passing this id.
+ */
+/** Independent-mode default org sentinel used by the local plane. */
+export declare const LOCAL_ORG_ID = "__default__";
+/** Stable name of the plane's local source (reused + re-pointed across runs). */
+export declare const LOCAL_SOURCE_NAME = "kici-local";
+/** Minimal surface of AdminApiClient plane-seed needs (for test injection). */
+export interface PlaneSeedClient {
+    listGenericSources(orgId: string, includeDeleted?: boolean): Promise<{
+        sources: Array<{
+            id: string;
+            name: string;
+            provider_type?: string;
+        }>;
+    }>;
+    createGenericSource(data: {
+        orgId: string;
+        name: string;
+        providerType?: string;
+        verificationMethod?: string;
+        localConfig?: {
+            repoBasePath: string;
+            cloneUrlBase?: string;
+            inPlace?: boolean;
+        };
+    }): Promise<{
+        source: {
+            id: string;
+            name: string;
+        };
+    }>;
+    updateGenericSource(id: string, data: {
+        localConfig?: {
+            repoBasePath: string;
+            cloneUrlBase?: string;
+            inPlace?: boolean;
+        } | null;
+    }): Promise<{
+        source: {
+            id: string;
+            name: string;
+        };
+    }>;
+}
+/** Result of seeding: the org + the (created or reused) source. */
+export interface SeededSource {
+    orgId: string;
+    sourceId: string;
+    sourceName: string;
+}
+/**
+ * Ensure the plane has a local `file://` source pointed at `repoDir`. Creates
+ * the `kici-local` source on first use; on subsequent runs it re-points the
+ * existing source at the new workdir (idempotent reuse). Returns the org +
+ * source ids the trigger uses.
+ */
+export declare function ensureLocalSource(planeUrl: string, adminToken: string, opts: {
+    repoDir: string;
+    orgId?: string;
+    name?: string;
+    /**
+     * In-place profile: `repoDir` is the operator's real working tree, so the
+     * plane skips the source-pack `__build__` job and each job runs the tree
+     * directly. Always written (true/false) so a subsequent isolated run resets
+     * a previously in-place source.
+     */
+    inPlace?: boolean;
+    client?: PlaneSeedClient;
+}): Promise<SeededSource>;
+//# sourceMappingURL=plane-seed.d.ts.map

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

@@ -0,0 +1,59 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { AdminApiClient } from "@kici-dev/orchestrator";
+//#region src/local-plane/plane-seed.ts
+/**
+* Seed the local `file://` source the plane dispatches an offline routed run
+* through. Idempotent: a stable `kici-local` source is created once and its
+* `repoBasePath` is re-pointed at the current workdir on every run (the isolated
+* profile materializes a fresh tmp clone each time). The org is the independent
+* orchestrator's `__default__` sentinel — the orchestrator DB has no org table,
+* so seeding an org is just passing this id.
+*/
+/** Independent-mode default org sentinel used by the local plane. */
+const LOCAL_ORG_ID = "__default__";
+/** Stable name of the plane's local source (reused + re-pointed across runs). */
+const LOCAL_SOURCE_NAME = "kici-local";
+/**
+* Ensure the plane has a local `file://` source pointed at `repoDir`. Creates
+* the `kici-local` source on first use; on subsequent runs it re-points the
+* existing source at the new workdir (idempotent reuse). Returns the org +
+* source ids the trigger uses.
+*/
+async function ensureLocalSource(planeUrl, adminToken, opts) {
+	const orgId = opts.orgId ?? "__default__";
+	const name = opts.name ?? "kici-local";
+	const inPlace = opts.inPlace === true;
+	const client = opts.client ?? new AdminApiClient(planeUrl, adminToken);
+	const { sources } = await client.listGenericSources(orgId);
+	const existing = sources.find((s) => s.name === name && s.provider_type === "local");
+	if (existing) {
+		const updated = await client.updateGenericSource(existing.id, { localConfig: {
+			repoBasePath: opts.repoDir,
+			inPlace
+		} });
+		return {
+			orgId,
+			sourceId: updated.source.id,
+			sourceName: updated.source.name
+		};
+	}
+	const created = await client.createGenericSource({
+		orgId,
+		name,
+		providerType: "local",
+		verificationMethod: "none",
+		localConfig: {
+			repoBasePath: opts.repoDir,
+			inPlace
+		}
+	});
+	return {
+		orgId,
+		sourceId: created.source.id,
+		sourceName: created.source.name
+	};
+}
+//#endregion
+export { LOCAL_ORG_ID, LOCAL_SOURCE_NAME, ensureLocalSource };
+
+//# sourceMappingURL=plane-seed.js.map

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

@@ -0,0 +1,71 @@
+/**
+ * Trigger an offline routed run against the local plane and discover its runId.
+ *
+ * A local repo has no forge to send a webhook, so this posts a GitHub-shaped
+ * synthetic push to the plane's provider-agnostic generic webhook route (the
+ * same wire shape the `kici-admin source trigger-local` path builds). The
+ * webhook is unauthenticated (the edge accepts it and returns 202); the run is
+ * created asynchronously, so this then polls the admin runs list — authenticated
+ * with the plane's bootstrap admin token — to resolve the created runId.
+ *
+ * The source's bundle hot-reload is debounced, so a first trigger can land
+ * before the plane has registered the (re-pointed) local source. This resends
+ * the webhook after a grace window until a run appears or the timeout elapses.
+ */
+/** A minimal admin-read client (AdminApiClient.get) — injectable for tests. */
+export interface RunDiscoveryClient {
+    get<T>(path: string): Promise<T>;
+}
+export interface LocalTriggerInput {
+    orgId: string;
+    sourceId: string;
+    repoFullName: string;
+    event: 'push' | 'pull_request' | 'dispatch';
+    ref: string;
+    sha: string;
+    defaultBranch: string;
+    /**
+     * Dispatch event action (`dispatch()` `types` matcher key). Only used when
+     * `event === 'dispatch'`; the local normalizer reads it from `payload.action`,
+     * so exactly one `types`-filtered workflow matches.
+     */
+    action?: string;
+    /** Dispatch `client_payload` (steps read `ctx.rawPayload.client_payload`). */
+    clientPayload?: unknown;
+}
+export interface LocalTriggerRequest {
+    path: string;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * Build the GitHub-shaped webhook request the plane's local provider normalizer
+ * expects. Mirrors `buildLocalTriggerRequest` in the orchestrator's
+ * `cli/commands/local-trigger.ts` (kept local to honour the compiler-only scope
+ * of this phase — no orchestrator export is added).
+ */
+export declare function buildLocalTriggerRequest(input: LocalTriggerInput): LocalTriggerRequest;
+/** Structured result of posting a local trigger to the plane. */
+export interface LocalTriggerResponse {
+    status: number;
+    /** Routing-key-scoped delivery id echoed by the plane, or null if absent. */
+    deliveryId: string | null;
+}
+/** POST the trigger request to the plane. Returns the status + delivery id. */
+export declare function sendLocalTrigger(planeUrl: string, req: LocalTriggerRequest): Promise<LocalTriggerResponse>;
+export interface TriggerRunOptions {
+    client?: RunDiscoveryClient;
+    pollIntervalMs?: number;
+    resendAfterMs?: number;
+    timeoutMs?: number;
+}
+/**
+ * Trigger the run and resolve its runId. Sends the synthetic push, then polls
+ * the admin runs list filtered by this webhook's routing-key-scoped delivery id
+ * (`?deliveryId=`), resending the webhook past a grace window to absorb source
+ * hot-reload latency. Correlating on the exact delivery id — rather than the
+ * newest run in a time window — guarantees the follower attaches to the run
+ * THIS invocation created, even when another local run lands concurrently.
+ */
+export declare function triggerRun(planeUrl: string, adminToken: string, input: LocalTriggerInput, opts?: TriggerRunOptions): Promise<string>;
+//# sourceMappingURL=plane-trigger.d.ts.map

package/dist/local-plane/plane-trigger.js

@@ -0,0 +1,110 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { randomUUID } from "node:crypto";
+import { AdminApiClient } from "@kici-dev/orchestrator";
+//#region src/local-plane/plane-trigger.ts
+/**
+* Trigger an offline routed run against the local plane and discover its runId.
+*
+* A local repo has no forge to send a webhook, so this posts a GitHub-shaped
+* synthetic push to the plane's provider-agnostic generic webhook route (the
+* same wire shape the `kici-admin source trigger-local` path builds). The
+* webhook is unauthenticated (the edge accepts it and returns 202); the run is
+* created asynchronously, so this then polls the admin runs list — authenticated
+* with the plane's bootstrap admin token — to resolve the created runId.
+*
+* The source's bundle hot-reload is debounced, so a first trigger can land
+* before the plane has registered the (re-pointed) local source. This resends
+* the webhook after a grace window until a run appears or the timeout elapses.
+*/
+/**
+* Build the GitHub-shaped webhook request the plane's local provider normalizer
+* expects. Mirrors `buildLocalTriggerRequest` in the orchestrator's
+* `cli/commands/local-trigger.ts` (kept local to honour the compiler-only scope
+* of this phase — no orchestrator export is added).
+*/
+function buildLocalTriggerRequest(input) {
+	const body = JSON.stringify({
+		ref: input.ref,
+		after: input.sha,
+		repository: {
+			full_name: input.repoFullName,
+			default_branch: input.defaultBranch
+		},
+		...input.event === "dispatch" && {
+			action: input.action,
+			client_payload: input.clientPayload ?? {}
+		}
+	});
+	return {
+		path: `/webhook/${input.orgId}/generic/${input.sourceId}`,
+		headers: {
+			"content-type": "application/json",
+			"x-event-type": input.event,
+			"x-delivery-id": randomUUID()
+		},
+		body
+	};
+}
+/** POST the trigger request to the plane. Returns the status + delivery id. */
+async function sendLocalTrigger(planeUrl, req) {
+	const res = await fetch(`${planeUrl.replace(/\/$/, "")}${req.path}`, {
+		method: "POST",
+		headers: req.headers,
+		body: req.body
+	});
+	let deliveryId = null;
+	try {
+		const parsed = await res.json();
+		if (typeof parsed.deliveryId === "string") deliveryId = parsed.deliveryId;
+	} catch {}
+	return {
+		status: res.status,
+		deliveryId
+	};
+}
+/**
+* Trigger the run and resolve its runId. Sends the synthetic push, then polls
+* the admin runs list filtered by this webhook's routing-key-scoped delivery id
+* (`?deliveryId=`), resending the webhook past a grace window to absorb source
+* hot-reload latency. Correlating on the exact delivery id — rather than the
+* newest run in a time window — guarantees the follower attaches to the run
+* THIS invocation created, even when another local run lands concurrently.
+*/
+async function triggerRun(planeUrl, adminToken, input, opts = {}) {
+	const client = opts.client ?? new AdminApiClient(planeUrl, adminToken);
+	const pollIntervalMs = opts.pollIntervalMs ?? 750;
+	const resendAfterMs = opts.resendAfterMs ?? 8e3;
+	const timeoutMs = opts.timeoutMs ?? 6e4;
+	const req = buildLocalTriggerRequest(input);
+	let deliveryId = (await sendLocalTrigger(planeUrl, req)).deliveryId;
+	let lastSend = Date.now();
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (deliveryId) {
+			const runId = await findRunByDelivery(client, deliveryId);
+			if (runId) return runId;
+		}
+		if (Date.now() - lastSend > resendAfterMs) {
+			deliveryId ??= (await sendLocalTrigger(planeUrl, req)).deliveryId;
+			lastSend = Date.now();
+		}
+		await sleep(pollIntervalMs);
+	}
+	throw new Error("offline run: no run appeared after triggering the local plane");
+}
+/** Return the run created by this webhook delivery, or null when none yet. */
+async function findRunByDelivery(client, deliveryId) {
+	const qs = new URLSearchParams({
+		deliveryId,
+		limit: "1"
+	});
+	const { runs } = await client.get(`/api/v1/admin/runs?${qs}`);
+	return runs[0]?.runId ?? null;
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+//#endregion
+export { buildLocalTriggerRequest, sendLocalTrigger, triggerRun };
+
+//# sourceMappingURL=plane-trigger.js.map

package/dist/local-plane/platform-attach.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Platform attach helpers for the local dev plane. Pure HTTP/URL helpers with no
+ * plane side-effects: derive the orchestrator WS relay URL from the CLI's HTTPS
+ * API base, mint/revoke an org-scoped orchestrator key via the Platform API
+ * using the logged-in personal access token, and probe Platform reachability.
+ *
+ * The minted key (prefix `kici_ok_`) is what the plane presents on WS auth when
+ * it boots hybrid. It is org-scoped and created under the calling user's own
+ * `api_keys:write` permission — attach never mints anything the user could not
+ * mint from the dashboard.
+ */
+/**
+ * Derive the orchestrator WS relay URL from the CLI's HTTPS Platform API base.
+ * `https://…` → `wss://…`, `http://…` → `ws://…`, then ensure a single trailing
+ * `/ws` path segment (idempotent when the base already ends in `/ws`).
+ */
+export declare function derivePlatformWsUrl(apiBase: string): string;
+export interface MintedOrchestratorKey {
+    /** Raw orchestrator key (kici_ok_…) — present once. NEVER log this. */
+    key: string;
+    /** Platform api_keys id (for later revoke). */
+    keyId: string;
+    keyPrefix: string;
+}
+/**
+ * Mint an org-scoped orchestrator key via the Platform HTTP API using the PAT.
+ * `POST ${apiBase}/api/v1/orgs/${orgId}/orchestrator-keys`.
+ */
+export declare function mintOrchestratorKey(args: {
+    apiBase: string;
+    pat: string;
+    orgId: string;
+    name?: string;
+}): Promise<MintedOrchestratorKey>;
+/**
+ * Best-effort revoke of a previously-minted orchestrator key on detach.
+ * `DELETE ${apiBase}/api/v1/orgs/${orgId}/orchestrator-keys/${keyId}`. Never
+ * throws — a failed revoke (offline, expired PAT) is non-fatal; the key is
+ * org-scoped and the local plane stops presenting it regardless.
+ */
+export declare function revokeOrchestratorKey(args: {
+    apiBase: string;
+    pat: string;
+    orgId: string;
+    keyId: string;
+}): Promise<boolean>;
+/**
+ * Bounded reachability probe against the Platform API base. Returns true when
+ * the base responds (any HTTP status — a reachable Platform, even a 401/404 on
+ * `/health`, proves the network path). A timeout / network error is false.
+ */
+export declare function probePlatformReachable(apiBase: string, timeoutMs?: number): Promise<boolean>;
+//# sourceMappingURL=platform-attach.d.ts.map

package/dist/local-plane/platform-attach.js

@@ -0,0 +1,107 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { toErrorMessage } from "@kici-dev/core";
+//#region src/local-plane/platform-attach.ts
+/**
+* Platform attach helpers for the local dev plane. Pure HTTP/URL helpers with no
+* plane side-effects: derive the orchestrator WS relay URL from the CLI's HTTPS
+* API base, mint/revoke an org-scoped orchestrator key via the Platform API
+* using the logged-in personal access token, and probe Platform reachability.
+*
+* The minted key (prefix `kici_ok_`) is what the plane presents on WS auth when
+* it boots hybrid. It is org-scoped and created under the calling user's own
+* `api_keys:write` permission — attach never mints anything the user could not
+* mint from the dashboard.
+*/
+/**
+* Derive the orchestrator WS relay URL from the CLI's HTTPS Platform API base.
+* `https://…` → `wss://…`, `http://…` → `ws://…`, then ensure a single trailing
+* `/ws` path segment (idempotent when the base already ends in `/ws`).
+*/
+function derivePlatformWsUrl(apiBase) {
+	let url;
+	try {
+		url = new URL(apiBase);
+	} catch {
+		throw new Error(`Invalid Platform API base URL: ${apiBase}`);
+	}
+	if (url.protocol === "https:") url.protocol = "wss:";
+	else if (url.protocol === "http:") url.protocol = "ws:";
+	else throw new Error(`Platform API base must be http(s): ${apiBase}`);
+	const trimmed = url.pathname.replace(/\/+$/, "");
+	url.pathname = trimmed.endsWith("/ws") ? trimmed : `${trimmed}/ws`;
+	url.search = "";
+	url.hash = "";
+	return url.toString();
+}
+/**
+* Mint an org-scoped orchestrator key via the Platform HTTP API using the PAT.
+* `POST ${apiBase}/api/v1/orgs/${orgId}/orchestrator-keys`.
+*/
+async function mintOrchestratorKey(args) {
+	const url = `${args.apiBase.replace(/\/+$/, "")}/api/v1/orgs/${encodeURIComponent(args.orgId)}/orchestrator-keys`;
+	let res;
+	try {
+		res = await fetch(url, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${args.pat}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({ name: args.name ?? `local dev plane (${orgHostLabel()})` })
+		});
+	} catch (err) {
+		throw new Error(`Could not reach the Platform to mint an orchestrator key: ${toErrorMessage(err)}`);
+	}
+	if (res.status === 401) throw new Error("Platform rejected the credentials (401). Run `kici login` to re-authenticate.");
+	if (res.status === 403) throw new Error(`Your account lacks permission to create orchestrator keys in org ${args.orgId} (needs the api_keys:write permission — an Owner can grant it).`);
+	if (!res.ok) throw new Error(`Platform returned ${res.status} minting the orchestrator key.`);
+	const body = await res.json();
+	if (!body.key || !body.id) throw new Error("Platform orchestrator-key response was missing the key or id.");
+	return {
+		key: body.key,
+		keyId: body.id,
+		keyPrefix: body.keyPrefix ?? "kici_ok_"
+	};
+}
+/**
+* Best-effort revoke of a previously-minted orchestrator key on detach.
+* `DELETE ${apiBase}/api/v1/orgs/${orgId}/orchestrator-keys/${keyId}`. Never
+* throws — a failed revoke (offline, expired PAT) is non-fatal; the key is
+* org-scoped and the local plane stops presenting it regardless.
+*/
+async function revokeOrchestratorKey(args) {
+	const url = `${args.apiBase.replace(/\/+$/, "")}/api/v1/orgs/${encodeURIComponent(args.orgId)}/orchestrator-keys/${encodeURIComponent(args.keyId)}`;
+	try {
+		return (await fetch(url, {
+			method: "DELETE",
+			headers: { Authorization: `Bearer ${args.pat}` }
+		})).ok;
+	} catch {
+		return false;
+	}
+}
+/**
+* Bounded reachability probe against the Platform API base. Returns true when
+* the base responds (any HTTP status — a reachable Platform, even a 401/404 on
+* `/health`, proves the network path). A timeout / network error is false.
+*/
+async function probePlatformReachable(apiBase, timeoutMs = 4e3) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const url = `${apiBase.replace(/\/+$/, "")}/health`;
+		return (await fetch(url, { signal: controller.signal })).status > 0;
+	} catch {
+		return false;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** A short, non-sensitive label for the minted key name (the machine host). */
+function orgHostLabel() {
+	return process.env.HOSTNAME || "kici-local";
+}
+//#endregion
+export { derivePlatformWsUrl, mintOrchestratorKey, probePlatformReachable, revokeOrchestratorKey };
+
+//# sourceMappingURL=platform-attach.js.map

package/dist/local-plane/port-holder.d.ts

@@ -0,0 +1,78 @@
+/** Command runner, injectable so each platform branch is unit-testable anywhere. */
+export type ExecFn = (cmd: string, args: string[]) => Promise<{
+    stdout: string;
+    exitCode: number;
+}>;
+/**
+ * Command line of process `pid`, or null when it cannot be determined.
+ *
+ * Linux exposes it as a NUL-separated `/proc` file; every other platform is
+ * asked through the same injectable `ExecFn` the port discovery above uses.
+ *
+ * **A null means "cannot tell", never "not that process."** Callers must treat
+ * it as an absence of evidence — the only safe reading when the answer decides
+ * whether to signal a pid.
+ */
+export declare function processCommandLine(pid: number, opts?: {
+    exec?: ExecFn;
+    platform?: NodeJS.Platform;
+    readProc?: (path: string) => string;
+}): Promise<string | null>;
+/**
+ * Whether the port can be bound on loopback. Probes `127.0.0.1` because that is
+ * the address the CLI talks to; a listener bound to `0.0.0.0` still makes this
+ * bind fail with EADDRINUSE, so there is no false "free".
+ */
+export declare function isPortFree(port: number): Promise<boolean>;
+/**
+ * Parse `ss -lptnH` rows. The process name is deliberately NOT matched — a Node
+ * listener reports as `MainThread` — so only `pid=N` is extracted. A row for a
+ * socket this user does not own carries no `users:(…)` field at all and yields
+ * null, which is what sends the caller to the lsof fallback.
+ */
+export declare function parseSsOutput(stdout: string, port: number): number | null;
+/**
+ * Parse `lsof -Fpn` field output, which is a stateful stream: each `p<pid>` line
+ * precedes the `n<address>` lines belonging to that pid.
+ */
+export declare function parseLsofOutput(stdout: string, port: number): number | null;
+/** Parse `netstat -ano -p tcp`: LISTENING rows only, pid in the last column. */
+export declare function parseNetstatOutput(stdout: string, port: number): number | null;
+/**
+ * Pid of the process listening on `port`, or null when it cannot be determined.
+ * Each platform runs the UNFILTERED listing and matches the port here rather
+ * than passing a filter expression to the tool, whose syntax is the fragile
+ * part. On Linux a null parse falls through to lsof as well as a non-zero exit,
+ * because ss omits the owning-process field for sockets this user does not own.
+ */
+export declare function findPortHolderPid(port: number, opts?: {
+    exec?: ExecFn;
+    platform?: NodeJS.Platform;
+}): Promise<number | null>;
+/** Signal sender, injectable so the escalation windows are unit-testable. */
+export type KillFn = (pid: number, signal: NodeJS.Signals | 0) => void;
+/**
+ * Poll until process `pid` has exited, sending SIGTERM first and escalating to
+ * SIGKILL past the grace window. `process.kill(pid, 0)` throws ESRCH once the
+ * process is gone. On Windows every signal terminates unconditionally, so the
+ * escalation collapses into a single hard kill there.
+ *
+ * Resolving does NOT prove the process died: a pid that survives SIGKILL (a
+ * zombie awaiting reaping, or a task wedged in uninterruptible I/O) is given
+ * `hardKillWaitMs` and then abandoned, because a teardown command that hangs
+ * forever is worse than one that reports the port is still held. Callers decide
+ * the outcome from the port itself — `waitForPortFree` — never from this
+ * resolving.
+ */
+export declare function terminatePid(pid: number, graceMs?: number, opts?: {
+    hardKillWaitMs?: number;
+    kill?: KillFn;
+}): Promise<void>;
+/**
+ * Poll until the port is bindable. This, not `terminatePid` resolving, is what
+ * decides a teardown: `terminatePid` abandons a pid that survives SIGKILL, and
+ * even a process that did exit can leave its listening socket lingering a moment
+ * longer on some platforms.
+ */
+export declare function waitForPortFree(port: number, timeoutMs?: number): Promise<boolean>;
+//# sourceMappingURL=port-holder.d.ts.map