@kici-dev/compiler 0.1.26 → 0.1.27

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

@@ -0,0 +1,151 @@
+/** Whether the plane runs offline (independent) or attached to the Platform (hybrid). */
+export type PlaneMode = 'independent' | 'hybrid';
+/**
+ * Attachment record for a hybrid plane: the Platform relay it dials, the org it
+ * is scoped to, and the Platform api_keys id of its minted orchestrator key (for
+ * later revoke). The orchestrator token itself is NEVER stored here — it lives
+ * in a sibling 0600 file so it can't land in a world-readable stamp.
+ */
+export interface PlaneAttachment {
+    /** Orchestrator KICI_PLATFORM_URL — a ws(s)://…/ws relay URL. */
+    platformWsUrl: string;
+    /** HTTPS Platform API base (provenance/verify context, key revoke). */
+    platformApiBase: string;
+    orgId: string;
+    /** Platform api_keys id of the minted orchestrator key. */
+    keyId: string;
+}
+/** On-disk record of the running plane, written on boot, read on status/down. */
+export interface PlaneStamp {
+    orchestratorPid: number;
+    port: number;
+    pgKind: 'embedded' | 'podman';
+    kiciVersion: string;
+    stampVersion: number;
+    /** Offline (independent) vs attached (hybrid). Absent (legacy) reads as independent. */
+    mode?: PlaneMode;
+}
+export interface PlaneStatus {
+    running: boolean;
+    pid?: number;
+    port?: number;
+    pgKind?: 'embedded' | 'podman';
+    stampVersion?: number;
+    url?: string;
+    /** Bootstrap admin token the CLI presents to the plane's admin API. */
+    adminToken?: string;
+    /** Offline (independent) vs attached (hybrid). */
+    mode: PlaneMode;
+    /** Present iff mode === 'hybrid'. */
+    attachment?: PlaneAttachment;
+}
+/**
+ * Read the plane's persisted Platform orchestrator token (mode 0600), or null
+ * when the plane is independent/offline. Kept out of the stamp so the token
+ * never lands in a world-readable file.
+ */
+export declare function readPlatformToken(): string | null;
+/** Persist the Platform orchestrator token (mode 0600). */
+export declare function writePlatformToken(token: string): void;
+/** Remove the persisted Platform orchestrator token (on detach). */
+export declare function clearPlatformToken(): void;
+/**
+ * Read the durable attachment record (survives `kici local down`), or null when
+ * the plane is not attached. This — not the running stamp — is the source of
+ * truth for "is this plane attached to the Platform".
+ */
+export declare function readAttachment(): PlaneAttachment | null;
+/** Persist the durable attachment record (never the token). */
+export declare function writeAttachment(attachment: PlaneAttachment): void;
+/** Remove the durable attachment record (on detach). */
+export declare function clearAttachment(): void;
+/**
+ * Read the plane's persisted bootstrap admin token, generating + persisting one
+ * (mode 0600) on first boot. A warm plane reuses the same token across CLI
+ * invocations so a running orchestrator keeps accepting the CLI's admin calls.
+ */
+export declare function readOrCreateAdminToken(): string;
+/** Read the plane's admin token without generating one (null when absent). */
+export declare function planeAdminToken(): string | null;
+/**
+ * Read the plane's local master secret key, generating + persisting a fresh 64
+ * hex-char key (mode 0600) on first boot. Stable across boots so DB-encrypted
+ * material stays decryptable. Freshly generated — never derived from any sops
+ * secret. Enables the orchestrator's secrets subsystem, which gates its admin
+ * API surface.
+ */
+export declare function readOrCreateSecretKey(): string;
+/** Absolute path of the dev-signed identity's private JWK key file. */
+export declare function devIdentityKeyFile(): string;
+/** Absolute path of the dev-signed identity's public JWK (written by the plane orchestrator). */
+export declare function devIdentityPublicJwkFile(): string;
+/**
+ * Read the plane's dev-signed identity keypair, generating + persisting a fresh
+ * EC P-256 private JWK (mode 0600) on first boot. Stable across boots so a
+ * `kici local trust-root` export stays valid for previously-minted tokens.
+ * Freshly generated — NEVER derived from any sops secret or real key. Only the
+ * private key is written here; the plane orchestrator derives + writes the
+ * public JWK next to it. Returns the private-key file path passed to the
+ * orchestrator via KICI_DEV_IDENTITY_KEY_FILE.
+ */
+export declare function readOrCreateDevIdentity(): string;
+/** Absolute path of the plane orchestrator's log file. */
+export declare function planeLogPath(): string;
+/** Read the plane's current status by probing `/ready` against the stamped port. */
+export declare function planeStatus(): Promise<PlaneStatus>;
+/** Attach parameters for a hybrid plane boot (see attachPlane). */
+export interface PlaneUpAttach {
+    platformWsUrl: string;
+    platformToken: string;
+    platformApiBase: string;
+    orgId: string;
+    keyId: string;
+}
+export interface PlaneUpOptions {
+    /** Boot the plane hybrid (attached to the Platform) instead of independent. */
+    attach?: PlaneUpAttach;
+}
+/**
+ * Start (or reuse) the local dev plane. Idempotent: a healthy running plane
+ * **whose stamped mode matches the requested mode** is returned as-is; a mode
+ * change (independent↔hybrid) forces a teardown + reboot. Otherwise Postgres +
+ * the orchestrator are booted and a fresh stamp + pidfile are written. When
+ * `attach` is present the orchestrator boots hybrid against the Platform relay;
+ * otherwise it boots independent with the dev-signed identity.
+ */
+export declare function planeUp(opts?: PlaneUpOptions): Promise<PlaneStatus>;
+/**
+ * Stop the local dev plane. Teardown is reconstructed from the stamp (the
+ * start-time Postgres handle does not survive a separate CLI invocation):
+ * SIGTERM the orchestrator, stop Postgres by backend kind, then clear the
+ * pidfile + stamp.
+ */
+export declare function planeDown(): Promise<void>;
+/**
+ * Poll until process `pid` has exited (SIGTERM already sent), escalating to
+ * SIGKILL if it outlives the grace period, so the caller can rely on the
+ * listening socket being released once this resolves. `process.kill(pid, 0)`
+ * throws `ESRCH` once the process is gone.
+ */
+export declare function waitForProcessExit(pid: number, graceMs?: number): Promise<void>;
+/**
+ * Attach the local dev plane to the hosted Platform: mint an org-scoped
+ * orchestrator key with the logged-in PAT, then (re)boot the plane hybrid
+ * against the Platform relay. Registration with the Platform is implicit — the
+ * hybrid orchestrator's PlatformClient sends `source.register` on WS auth.
+ */
+export declare function attachPlane(args: {
+    apiBase: string;
+    pat: string;
+    orgId: string;
+}): Promise<PlaneStatus>;
+/**
+ * Detach the local dev plane: best-effort revoke the minted orchestrator key on
+ * the Platform, clear the durable attachment + token, then reboot the plane
+ * independent (offline). The revoke is non-fatal — a detach must succeed even
+ * offline or with an expired PAT.
+ */
+export declare function detachPlane(opts?: {
+    pat?: string;
+}): Promise<PlaneStatus>;
+//# sourceMappingURL=plane-manager.d.ts.map

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

@@ -0,0 +1,340 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { planePaths, planePorts } from "./paths.js";
+import { orchestratorReady, spawnOrchestrator } from "./orchestrator-process.js";
+import { startPlanePostgres, stopPlanePostgres } from "./postgres.js";
+import { writeScalerConfig } from "./scaler-config.js";
+import { derivePlatformWsUrl, mintOrchestratorKey, revokeOrchestratorKey } from "./platform-attach.js";
+import path from "node:path";
+import fs from "node:fs";
+import { generateKeyPairSync, randomBytes } from "node:crypto";
+//#region src/local-plane/plane-manager.ts
+const kiciVersion = "0.1.27";
+/**
+* Read the plane's persisted Platform orchestrator token (mode 0600), or null
+* when the plane is independent/offline. Kept out of the stamp so the token
+* never lands in a world-readable file.
+*/
+function readPlatformToken() {
+	try {
+		return fs.readFileSync(planePaths().platformTokenFile, "utf-8").trim() || null;
+	} catch {
+		return null;
+	}
+}
+/** Persist the Platform orchestrator token (mode 0600). */
+function writePlatformToken(token) {
+	const { platformTokenFile, root } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	fs.writeFileSync(platformTokenFile, token, { mode: 384 });
+}
+/** Remove the persisted Platform orchestrator token (on detach). */
+function clearPlatformToken() {
+	fs.rmSync(planePaths().platformTokenFile, { force: true });
+}
+/**
+* Read the durable attachment record (survives `kici local down`), or null when
+* the plane is not attached. This — not the running stamp — is the source of
+* truth for "is this plane attached to the Platform".
+*/
+function readAttachment() {
+	try {
+		return JSON.parse(fs.readFileSync(planePaths().attachmentFile, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+/** Persist the durable attachment record (never the token). */
+function writeAttachment(attachment) {
+	const { attachmentFile, root } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	fs.writeFileSync(attachmentFile, JSON.stringify(attachment, null, 2));
+}
+/** Remove the durable attachment record (on detach). */
+function clearAttachment() {
+	fs.rmSync(planePaths().attachmentFile, { force: true });
+}
+/**
+* Read the plane's persisted bootstrap admin token, generating + persisting one
+* (mode 0600) on first boot. A warm plane reuses the same token across CLI
+* invocations so a running orchestrator keeps accepting the CLI's admin calls.
+*/
+function readOrCreateAdminToken() {
+	const { adminTokenFile, root } = planePaths();
+	try {
+		const existing = fs.readFileSync(adminTokenFile, "utf-8").trim();
+		if (existing) return existing;
+	} catch {}
+	fs.mkdirSync(root, { recursive: true });
+	const token = `kici-local-${randomBytes(24).toString("hex")}`;
+	fs.writeFileSync(adminTokenFile, token, { mode: 384 });
+	return token;
+}
+/** Read the plane's admin token without generating one (null when absent). */
+function planeAdminToken() {
+	try {
+		return fs.readFileSync(planePaths().adminTokenFile, "utf-8").trim() || null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Read the plane's local master secret key, generating + persisting a fresh 64
+* hex-char key (mode 0600) on first boot. Stable across boots so DB-encrypted
+* material stays decryptable. Freshly generated — never derived from any sops
+* secret. Enables the orchestrator's secrets subsystem, which gates its admin
+* API surface.
+*/
+function readOrCreateSecretKey() {
+	const { secretKeyFile, root } = planePaths();
+	try {
+		const existing = fs.readFileSync(secretKeyFile, "utf-8").trim();
+		if (existing) return existing;
+	} catch {}
+	fs.mkdirSync(root, { recursive: true });
+	const key = randomBytes(32).toString("hex");
+	fs.writeFileSync(secretKeyFile, key, { mode: 384 });
+	return key;
+}
+/** Absolute path of the dev-signed identity's private JWK key file. */
+function devIdentityKeyFile() {
+	return path.join(planePaths().devIdentityDir, "identity.jwk");
+}
+/** Absolute path of the dev-signed identity's public JWK (written by the plane orchestrator). */
+function devIdentityPublicJwkFile() {
+	return path.join(planePaths().devIdentityDir, "identity.pub.jwk");
+}
+/**
+* Read the plane's dev-signed identity keypair, generating + persisting a fresh
+* EC P-256 private JWK (mode 0600) on first boot. Stable across boots so a
+* `kici local trust-root` export stays valid for previously-minted tokens.
+* Freshly generated — NEVER derived from any sops secret or real key. Only the
+* private key is written here; the plane orchestrator derives + writes the
+* public JWK next to it. Returns the private-key file path passed to the
+* orchestrator via KICI_DEV_IDENTITY_KEY_FILE.
+*/
+function readOrCreateDevIdentity() {
+	const keyFile = devIdentityKeyFile();
+	try {
+		if (fs.readFileSync(keyFile, "utf-8").trim()) return keyFile;
+	} catch {}
+	fs.mkdirSync(planePaths().devIdentityDir, {
+		recursive: true,
+		mode: 448
+	});
+	const { privateKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
+	const jwk = privateKey.export({ format: "jwk" });
+	fs.writeFileSync(keyFile, JSON.stringify(jwk, null, 2), { mode: 384 });
+	return keyFile;
+}
+function readStamp() {
+	try {
+		return JSON.parse(fs.readFileSync(planePaths().stampFile, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+function writeStamp(stamp) {
+	const { root, stampFile, pidfile } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	fs.writeFileSync(stampFile, JSON.stringify(stamp, null, 2));
+	fs.writeFileSync(pidfile, String(stamp.orchestratorPid));
+}
+function orchestratorUrl(port) {
+	return `http://127.0.0.1:${port}`;
+}
+/** Absolute path of the plane orchestrator's log file. */
+function planeLogPath() {
+	return planePaths().logFile;
+}
+/** Read the plane's current status by probing `/ready` against the stamped port. */
+async function planeStatus() {
+	const stamp = readStamp();
+	const port = stamp?.port ?? planePorts().orchestrator;
+	if (!await orchestratorReady(port)) return {
+		running: false,
+		mode: stamp?.mode ?? "independent",
+		attachment: readAttachment() ?? void 0
+	};
+	return {
+		running: true,
+		pid: stamp?.orchestratorPid,
+		port,
+		pgKind: stamp?.pgKind,
+		stampVersion: stamp?.stampVersion,
+		url: orchestratorUrl(port),
+		adminToken: planeAdminToken() ?? void 0,
+		mode: stamp?.mode ?? "independent",
+		attachment: readAttachment() ?? void 0
+	};
+}
+/**
+* Start (or reuse) the local dev plane. Idempotent: a healthy running plane
+* **whose stamped mode matches the requested mode** is returned as-is; a mode
+* change (independent↔hybrid) forces a teardown + reboot. Otherwise Postgres +
+* the orchestrator are booted and a fresh stamp + pidfile are written. When
+* `attach` is present the orchestrator boots hybrid against the Platform relay;
+* otherwise it boots independent with the dev-signed identity.
+*/
+async function planeUp(opts = {}) {
+	const { orchestrator: port } = planePorts();
+	const existing = readStamp();
+	const requestedMode = opts.attach ? "hybrid" : "independent";
+	if (existing && existing.stampVersion !== 3) {
+		await planeDown();
+		fs.rmSync(planePaths().pgData, {
+			recursive: true,
+			force: true
+		});
+	} else if ((existing?.mode ?? "independent") !== requestedMode && await orchestratorReady(port)) await planeDown();
+	else if (await orchestratorReady(port)) return {
+		running: true,
+		pid: existing?.orchestratorPid,
+		port,
+		pgKind: existing?.pgKind,
+		stampVersion: existing?.stampVersion,
+		url: orchestratorUrl(port),
+		adminToken: planeAdminToken() ?? void 0,
+		mode: existing?.mode ?? "independent",
+		attachment: readAttachment() ?? void 0
+	};
+	const adminToken = readOrCreateAdminToken();
+	const secretKey = readOrCreateSecretKey();
+	const scalerConfigFile = writeScalerConfig(port);
+	const pg = await startPlanePostgres();
+	let orch;
+	if (opts.attach) {
+		writePlatformToken(opts.attach.platformToken);
+		writeAttachment({
+			platformWsUrl: opts.attach.platformWsUrl,
+			platformApiBase: opts.attach.platformApiBase,
+			orgId: opts.attach.orgId,
+			keyId: opts.attach.keyId
+		});
+		orch = await spawnOrchestrator(pg.url, {
+			adminToken,
+			secretKey,
+			scalerConfigFile,
+			attach: {
+				platformWsUrl: opts.attach.platformWsUrl,
+				platformToken: opts.attach.platformToken
+			}
+		});
+	} else {
+		const devIdentityKey = readOrCreateDevIdentity();
+		orch = await spawnOrchestrator(pg.url, {
+			adminToken,
+			secretKey,
+			scalerConfigFile,
+			devIdentityKeyFile: devIdentityKey
+		});
+	}
+	writeStamp({
+		orchestratorPid: orch.pid,
+		port: orch.port,
+		pgKind: pg.kind,
+		kiciVersion,
+		stampVersion: 3,
+		mode: requestedMode
+	});
+	return {
+		running: true,
+		pid: orch.pid,
+		port: orch.port,
+		pgKind: pg.kind,
+		stampVersion: 3,
+		url: orchestratorUrl(orch.port),
+		adminToken,
+		mode: requestedMode,
+		attachment: readAttachment() ?? void 0
+	};
+}
+/**
+* Stop the local dev plane. Teardown is reconstructed from the stamp (the
+* start-time Postgres handle does not survive a separate CLI invocation):
+* SIGTERM the orchestrator, stop Postgres by backend kind, then clear the
+* pidfile + stamp.
+*/
+async function planeDown() {
+	const stamp = readStamp();
+	const { pidfile, stampFile } = planePaths();
+	if (stamp) {
+		try {
+			process.kill(stamp.orchestratorPid, "SIGTERM");
+		} catch {}
+		await waitForProcessExit(stamp.orchestratorPid);
+		await stopPlanePostgres(stamp.pgKind);
+	}
+	fs.rmSync(pidfile, { force: true });
+	fs.rmSync(stampFile, { force: true });
+}
+/**
+* Poll until process `pid` has exited (SIGTERM already sent), escalating to
+* SIGKILL if it outlives the grace period, so the caller can rely on the
+* listening socket being released once this resolves. `process.kill(pid, 0)`
+* throws `ESRCH` once the process is gone.
+*/
+async function waitForProcessExit(pid, graceMs = 1e4) {
+	const deadline = Date.now() + graceMs;
+	let killed = false;
+	for (;;) {
+		try {
+			process.kill(pid, 0);
+		} catch {
+			return;
+		}
+		if (!killed && Date.now() > deadline) {
+			try {
+				process.kill(pid, "SIGKILL");
+			} catch {
+				return;
+			}
+			killed = true;
+		}
+		await new Promise((r) => setTimeout(r, 100));
+	}
+}
+/**
+* Attach the local dev plane to the hosted Platform: mint an org-scoped
+* orchestrator key with the logged-in PAT, then (re)boot the plane hybrid
+* against the Platform relay. Registration with the Platform is implicit — the
+* hybrid orchestrator's PlatformClient sends `source.register` on WS auth.
+*/
+async function attachPlane(args) {
+	const platformWsUrl = derivePlatformWsUrl(args.apiBase);
+	const minted = await mintOrchestratorKey({
+		apiBase: args.apiBase,
+		pat: args.pat,
+		orgId: args.orgId,
+		name: "local dev plane"
+	});
+	return planeUp({ attach: {
+		platformWsUrl,
+		platformToken: minted.key,
+		platformApiBase: args.apiBase,
+		orgId: args.orgId,
+		keyId: minted.keyId
+	} });
+}
+/**
+* Detach the local dev plane: best-effort revoke the minted orchestrator key on
+* the Platform, clear the durable attachment + token, then reboot the plane
+* independent (offline). The revoke is non-fatal — a detach must succeed even
+* offline or with an expired PAT.
+*/
+async function detachPlane(opts = {}) {
+	const attachment = readAttachment();
+	if (attachment && opts.pat) await revokeOrchestratorKey({
+		apiBase: attachment.platformApiBase,
+		pat: opts.pat,
+		orgId: attachment.orgId,
+		keyId: attachment.keyId
+	}).catch(() => false);
+	clearAttachment();
+	clearPlatformToken();
+	await planeDown();
+	return planeUp();
+}
+//#endregion
+export { attachPlane, clearAttachment, clearPlatformToken, detachPlane, devIdentityKeyFile, devIdentityPublicJwkFile, planeAdminToken, planeDown, planeLogPath, planeStatus, planeUp, readAttachment, readOrCreateAdminToken, readOrCreateDevIdentity, readOrCreateSecretKey, readPlatformToken, waitForProcessExit, writeAttachment, writePlatformToken };
+
+//# sourceMappingURL=plane-manager.js.map

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,62 @@
+/**
+ * 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;
+/** POST the trigger request to the plane. Returns the HTTP status. */
+export declare function sendLocalTrigger(planeUrl: string, req: LocalTriggerRequest): Promise<number>;
+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 (`created_at > since`) for the newest run, resending the
+ * webhook past a grace window to absorb source hot-reload latency.
+ */
+export declare function triggerRun(planeUrl: string, adminToken: string, input: LocalTriggerInput, opts?: TriggerRunOptions): Promise<string>;
+//# sourceMappingURL=plane-trigger.d.ts.map