@kici-dev/compiler 0.7.0 → 0.8.0

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

@@ -1,4 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { EventLogStatus } from "@kici-dev/engine";
 import { randomUUID } from "node:crypto";
 import { AdminApiClient } from "@kici-dev/orchestrator";
 //#region src/local-plane/plane-trigger.ts
@@ -15,6 +16,9 @@ import { AdminApiClient } from "@kici-dev/orchestrator";
 * 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.
+* When the budget still runs out, the timeout is explained rather than merely
+* reported: the plane's own Raft role and its event-log record for this
+* delivery decide which cause is named.
 */
 /**
 * Build the GitHub-shaped webhook request the plane's local provider normalizer
@@ -62,6 +66,50 @@ async function sendLocalTrigger(planeUrl, req) {
 		deliveryId
 	};
 }
+/** Raft role the plane reports, or null when `/cluster/health` cannot be read. */
+async function readPlaneRole(client) {
+	try {
+		const health = await client.get("/cluster/health");
+		return typeof health.role === "string" ? health.role : null;
+	} catch {
+		return null;
+	}
+}
+/** The plane's own record of this delivery, or null when there is none to read. */
+async function readDelivery(client, orgId, deliveryId) {
+	try {
+		const qs = new URLSearchParams({
+			deliveryId,
+			orgId,
+			limit: "1"
+		});
+		return (await client.get(`/api/v1/admin/event-log?${qs}`)).deliveries?.[0] ?? null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Explain a trigger timeout in one line, from what the plane itself recorded.
+*
+* Ordered most-specific-first, and every branch is a fact read back off the
+* plane rather than an inference: the Raft role it reports, then the status it
+* wrote for THIS delivery, then the delivery id + log path so the developer has
+* a thread to pull even when neither surface answered.
+*/
+async function diagnoseTriggerTimeout(client, ctx) {
+	const role = await readPlaneRole(client);
+	if (role !== null && role !== "leader") return `plane is not leader yet (election grace period) — it reports Raft role "${role}". A single-node plane should elect itself within seconds; check ${ctx.logPath ?? "the plane log (`kici local logs`)"} for "self-electing as leader".`;
+	const delivery = ctx.deliveryId ? await readDelivery(client, ctx.orgId, ctx.deliveryId) : null;
+	if (delivery?.status === EventLogStatus.enum.lockfile_missing) {
+		const where = ctx.repoBasePath ? ` in ${ctx.repoBasePath}` : "";
+		return `no kici.lock.json at ${ctx.sha}${where} — the plane resolved no lock file for this commit, so nothing matched. Make sure .kici/kici.lock.json is committed or present in the working tree the run packs.`;
+	}
+	if (delivery?.status) {
+		const detail = delivery.errorMessage ? ` (${delivery.errorMessage})` : "";
+		return `the plane recorded delivery ${ctx.deliveryId} as "${delivery.status}"${detail} but created no run.`;
+	}
+	return `no run appeared for ${ctx.deliveryId ? `delivery ${ctx.deliveryId}` : "this trigger — the plane never accepted the webhook (no delivery id came back)"}${ctx.logPath ? ` — see ${ctx.logPath}` : ""}`;
+}
 /**
 * 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
@@ -90,7 +138,14 @@ async function triggerRun(planeUrl, adminToken, input, opts = {}) {
 		}
 		await sleep(pollIntervalMs);
 	}
-	throw new Error("offline run: no run appeared after triggering the local plane");
+	const cause = await diagnoseTriggerTimeout(client, {
+		deliveryId,
+		orgId: input.orgId,
+		sha: input.sha,
+		...opts.repoBasePath !== void 0 && { repoBasePath: opts.repoBasePath },
+		...opts.logPath !== void 0 && { logPath: opts.logPath }
+	});
+	throw new Error(`offline run: ${cause}`);
 }
 /** Return the run created by this webhook delivery, or null when none yet. */
 async function findRunByDelivery(client, deliveryId) {
@@ -105,6 +160,6 @@ function sleep(ms) {
 	return new Promise((r) => setTimeout(r, ms));
 }
 //#endregion
-export { buildLocalTriggerRequest, sendLocalTrigger, triggerRun };
+export { buildLocalTriggerRequest, diagnoseTriggerTimeout, sendLocalTrigger, triggerRun };
 
 //# sourceMappingURL=plane-trigger.js.map

package/dist/local-plane/postgres.js

@@ -1,5 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { planePaths, planePorts } from "./paths.js";
+import { rotatePlaneLogIfOversized } from "./plane-log.js";
 import { createRequire } from "node:module";
 import path from "node:path";
 import fs from "node:fs";
@@ -104,14 +105,13 @@ async function embeddedClusterIsServing(port) {
 /**
 * Start a detached embedded postmaster via `pg_ctl` so it survives the exit of
 * this CLI process (embedded-postgres's in-process server is killed by its own
-* exit hook, so it cannot back a warm plane). A cluster already serving this
-* plane's port is reused as-is.
+* exit hook, so it cannot back a warm plane). The caller decides whether a
+* cluster is already serving; this always starts one.
 */
 async function defaultEmbeddedDaemon(port) {
-	const { pgData, logFile } = planePaths();
-	if (await embeddedClusterIsServing(port)) return;
+	const { pgData, pgLogFile } = planePaths();
 	const pgCtl = resolvePgCtl();
-	await $`${pgCtl} -D ${pgData} -o ${`-p ${port}`} -l ${`${logFile}.pg`} -w start`.quiet();
+	await $`${pgCtl} -D ${pgData} -o ${`-p ${port}`} -l ${pgLogFile} -w start`.quiet();
 }
 /** Stop the detached embedded postmaster (handle-independent, reads the data dir). */
 async function stopEmbeddedDaemon() {
@@ -141,7 +141,10 @@ async function startPlanePostgres(opts = {}) {
 	const url = `postgres://kici:kici@127.0.0.1:${port}/kici_local`;
 	if (!(opts.forcePodman || process.env.KICI_LOCAL_PG_MODE === "podman")) try {
 		await ensureEmbeddedCluster(port);
-		await embeddedDaemon(port);
+		if (!await embeddedClusterIsServing(port)) {
+			rotatePlaneLogIfOversized(planePaths().pgLogFile);
+			await embeddedDaemon(port);
+		}
 		return {
 			url,
 			kind: "embedded",

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

@@ -1,4 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { unwrapStoredLogLine } from "../remote/output/streaming.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
@@ -131,7 +132,7 @@ async function drainLogs(client, runId, cursors, onLine) {
 				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);
+					onLine(unwrapStoredLogLine(l.value));
 					emitted++;
 				}
 				cursor = page.nextCursor ?? String(page.totalLines);

package/dist/remote/output/streaming.d.ts

@@ -7,6 +7,18 @@
  * - Prints step transition headers
  * - Tracks elapsed time with in-place status updates
  */
+/**
+ * The text a stored log line carries.
+ *
+ * The orchestrator stores every step log line as a JSON envelope —
+ * `{"ts":…,"level":"stdout","msg":"…","meta":{}}` — and the Platform relay
+ * returns those envelopes verbatim, so a run's log stream is the envelope
+ * stream. The dashboard unwraps `msg` before rendering; the terminal must too,
+ * or the developer watching `kici run remote` reads raw JSON. A line that is
+ * not an envelope (an orchestrator phase marker, a plain line from an older
+ * store) passes through unchanged.
+ */
+export declare function unwrapStoredLogLine(line: string): string;
 export declare class StreamingFormatter {
     /** Color assignment per job name. */
     private readonly jobColors;

package/dist/remote/output/streaming.js

@@ -19,6 +19,25 @@ const COLOR_PALETTE = [
 	pc.magenta,
 	pc.cyan
 ];
+/**
+* The text a stored log line carries.
+*
+* The orchestrator stores every step log line as a JSON envelope —
+* `{"ts":…,"level":"stdout","msg":"…","meta":{}}` — and the Platform relay
+* returns those envelopes verbatim, so a run's log stream is the envelope
+* stream. The dashboard unwraps `msg` before rendering; the terminal must too,
+* or the developer watching `kici run remote` reads raw JSON. A line that is
+* not an envelope (an orchestrator phase marker, a plain line from an older
+* store) passes through unchanged.
+*/
+function unwrapStoredLogLine(line) {
+	if (!line.startsWith("{")) return line;
+	try {
+		const parsed = JSON.parse(line);
+		if (typeof parsed === "object" && parsed !== null && typeof parsed.msg === "string") return parsed.msg;
+	} catch {}
+	return line;
+}
 var StreamingFormatter = class {
 	/** Color assignment per job name. */
 	jobColors = /* @__PURE__ */ new Map();
@@ -119,6 +138,6 @@ var StreamingFormatter = class {
 	}
 };
 //#endregion
-export { StreamingFormatter };
+export { StreamingFormatter, unwrapStoredLogLine };
 
 //# sourceMappingURL=streaming.js.map

package/dist/remote/platform-client.d.ts

@@ -106,6 +106,8 @@ export interface PlatformRunStatusResponse {
         status: string;
         exitCode?: number | null;
         errorMessage?: string | null;
+        /** Absent or null from an orchestrator that does not report it. */
+        durationMs?: number | null;
     }>;
     done: boolean;
 }

package/dist/templates/package-json.d.ts

@@ -7,11 +7,14 @@
  * The compiler is invoked via npx (not installed as a dependency).
  */
 /**
- * The npm version range the scaffold pins `@kici-dev/sdk` to.
+ * The npm version spec the scaffold pins `@kici-dev/sdk` to.
  *
- * @param devMode - When true, a prerelease-compatible range (`>=0.0.1-0`) so
- *   npm resolves Verdaccio's prerelease builds (e.g. 0.0.1-2856). Semver
- *   `^0.0.1` does NOT match prereleases, causing 404s on Verdaccio.
+ * @param devMode - When true, the `latest` dist-tag, so npm resolves whatever
+ *   build the dev registry (Verdaccio) currently publishes. Dev builds are
+ *   prereleases such as `0.8.0-9726`, and no semver range reaches them: a
+ *   prerelease only satisfies a comparator with the same major.minor.patch, so
+ *   `^0.0.1` misses every one and `>=0.0.1-0` misses every one past 0.0.1.
+ *   A dist-tag is resolved by name, never by range, so it follows the counter.
  */
 export declare function sdkDependencyRange(devMode?: boolean): string;
 /**
@@ -24,9 +27,8 @@ export declare const TYPESCRIPT_RANGE = "^6.0.3";
 /**
  * Generate package.json content for .kici/ directory
  *
- * @param devMode - When true, uses a prerelease-compatible version range
- *   (`>=0.0.1-0`) so npm resolves Verdaccio's prerelease builds (e.g. 0.0.1-2856).
- *   Semver `^0.0.1` does NOT match prereleases, causing 404s on Verdaccio.
+ * @param devMode - When true, pins the SDK to the `latest` dist-tag so npm
+ *   resolves the dev registry's newest prerelease build (see sdkDependencyRange).
  * @returns JSON string with proper formatting (2-space indent, trailing newline)
  */
 export declare function generatePackageJson(devMode?: boolean): string;

package/dist/templates/package-json.js

@@ -1,15 +1,18 @@
 import "../rolldown-runtime-ClRpJifh.js";
 //#region src/templates/package-json.ts
-const sdkVersion = "0.7.0";
+const sdkVersion = "0.8.0";
 /**
-* The npm version range the scaffold pins `@kici-dev/sdk` to.
+* The npm version spec the scaffold pins `@kici-dev/sdk` to.
 *
-* @param devMode - When true, a prerelease-compatible range (`>=0.0.1-0`) so
-*   npm resolves Verdaccio's prerelease builds (e.g. 0.0.1-2856). Semver
-*   `^0.0.1` does NOT match prereleases, causing 404s on Verdaccio.
+* @param devMode - When true, the `latest` dist-tag, so npm resolves whatever
+*   build the dev registry (Verdaccio) currently publishes. Dev builds are
+*   prereleases such as `0.8.0-9726`, and no semver range reaches them: a
+*   prerelease only satisfies a comparator with the same major.minor.patch, so
+*   `^0.0.1` misses every one and `>=0.0.1-0` misses every one past 0.0.1.
+*   A dist-tag is resolved by name, never by range, so it follows the counter.
 */
 function sdkDependencyRange(devMode = false) {
-	return devMode ? ">=0.0.1-0" : `^${sdkVersion}`;
+	return devMode ? "latest" : `^${sdkVersion}`;
 }
 /**
 * The TypeScript range scaffolded into a `.kici` workspace. Pinned to the major
@@ -21,9 +24,8 @@ const TYPESCRIPT_RANGE = "^6.0.3";
 /**
 * Generate package.json content for .kici/ directory
 *
-* @param devMode - When true, uses a prerelease-compatible version range
-*   (`>=0.0.1-0`) so npm resolves Verdaccio's prerelease builds (e.g. 0.0.1-2856).
-*   Semver `^0.0.1` does NOT match prereleases, causing 404s on Verdaccio.
+* @param devMode - When true, pins the SDK to the `latest` dist-tag so npm
+*   resolves the dev registry's newest prerelease build (see sdkDependencyRange).
 * @returns JSON string with proper formatting (2-space indent, trailing newline)
 */
 function generatePackageJson(devMode = false) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/compiler",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Compiler and CLI for KiCI workflows. Compiles `.kici/workflows/*.ts` to a `kici.lock.json` file consumed by the orchestrator and agents, and runs workflows locally or against a remote orchestrator.",
   "keywords": [
     "ci",
@@ -61,17 +61,17 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/agent": "0.7.0",
-    "@kici-dev/orchestrator": "0.7.0",
-    "@kici-dev/core": "0.7.0",
-    "@kici-dev/engine": "0.7.0"
+    "@kici-dev/agent": "0.8.0",
+    "@kici-dev/core": "0.8.0",
+    "@kici-dev/engine": "0.8.0",
+    "@kici-dev/orchestrator": "0.8.0"
   },
   "devDependencies": {
     "@types/archiver": "^8.0.0",
     "jszip": "^3.10.1"
   },
   "peerDependencies": {
-    "@kici-dev/sdk": "0.7.0"
+    "@kici-dev/sdk": "0.8.0"
   },
   "scripts": {
     "build": "node ../../scripts/build-ts.mjs && tsgo --emitDeclarationOnly",