@kici-dev/compiler 0.1.27 → 0.3.0

package/dist/local-plane/source-provider.js

@@ -3,8 +3,7 @@ import { selectOverlayFiles } from "../remote/uploader.js";
 import path from "node:path";
 import fs from "node:fs/promises";
 import { execFileSync, execSync } from "node:child_process";
-import os from "node:os";
-import { randomBytes } from "node:crypto";
+import { makeTempDir } from "@kici-dev/core/tmp";
 //#region src/local-plane/source-provider.ts
 /**
 * LocalSourceProvider — resolve the workdir a `kici run --local` dispatch
@@ -59,8 +58,8 @@ function resolveInPlace(repoRoot) {
 * carries the work.
 */
 async function resolveIsolated(repoRoot) {
-	const base = os.tmpdir();
-	const tmpDir = path.join(base, `kici-local-run-${randomBytes(3).toString("hex")}`);
+	const workdir = await makeTempDir("local-run", { persist: true });
+	const tmpDir = workdir.path;
 	const { sha, existingFiles, deletedFiles } = await selectOverlayFiles(repoRoot);
 	execSync(`git clone --no-hardlinks --quiet ${shellQuote(repoRoot)} ${shellQuote(tmpDir)}`, { stdio: "ignore" });
 	execSync(`git checkout --quiet ${sha}`, {
@@ -100,12 +99,7 @@ async function resolveIsolated(repoRoot) {
 		ref: `refs/heads/${LOCAL_RUN_BRANCH}`,
 		sha: committed,
 		branch: LOCAL_RUN_BRANCH,
-		cleanup: async () => {
-			await fs.rm(tmpDir, {
-				recursive: true,
-				force: true
-			});
-		}
+		cleanup: () => workdir.cleanup()
 	};
 }
 /** Copy overlay files onto the clone and remove local deletions. */

package/dist/lockfile/generator.d.ts

@@ -1,5 +1,18 @@
 import type { StepInput, TriggerConfig } from '@kici-dev/sdk';
 import { type LockFile, type LockTrigger, type LockStepEntry, type WorkflowWithSource } from '../types.js';
+import { type SourceLocation } from '../errors/index.js';
+/**
+ * Courtesy compatibility warning for `kici compile`.
+ *
+ * When the current schema version is itself a breaking version
+ * (`floor === version`), locks emitted now stamp `minReaderVersion = version`
+ * and cannot be read by orchestrators older than that version — return a
+ * one-line heads-up naming the required orchestrator schema. When the floor sits
+ * below the current version (`floor < version`) the emitted lock is additive
+ * over older readers down to the floor, so no warning is warranted (return
+ * null). The orchestrator remains the authoritative reject; this is informational.
+ */
+export declare function schemaWindowWarning(floor: number, version: number): string | null;
 /**
  * Detect git repository root by running `git rev-parse --show-toplevel`.
  * Falls back to cwd if not in a git repo.
@@ -47,7 +60,7 @@ export declare function transformTriggers(triggers?: TriggerConfig[]): readonly
  * compiler's naming matches the agent's `extractAndNormalizeSteps` enumeration —
  * the flat-stepIndex invariant.
  */
-export declare function transformSteps(steps: readonly StepInput[], gitRoot: string): readonly LockStepEntry[];
+export declare function transformSteps(steps: readonly StepInput[], gitRoot: string, jobLocation?: SourceLocation): readonly LockStepEntry[];
 /**
  * Serialize lock file to JSON string.
  *

package/dist/lockfile/generator.js

@@ -1,5 +1,8 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { SCHEMA_VERSION as SCHEMA_VERSION$1 } from "../types.js";
+import { compilerError } from "../errors/formatter.js";
+import { locationForJob, locationForWorkflow } from "../errors/source-location.js";
+import "../errors/index.js";
+import { BREAKING_FLOOR as BREAKING_FLOOR$1, SCHEMA_VERSION as SCHEMA_VERSION$1 } from "../types.js";
 import { computeContentHash } from "./hasher.js";
 import { resolveHashFiles } from "./hash-files.js";
 import { analyzePurity } from "./purity-analyzer.js";
@@ -13,6 +16,21 @@ import { normalizeRunsOnAllToMatchers, normalizeRunsOnToMatchers, runsOnPickFrom
 import { execSync } from "node:child_process";
 //#region src/lockfile/generator.ts
 /**
+* Courtesy compatibility warning for `kici compile`.
+*
+* When the current schema version is itself a breaking version
+* (`floor === version`), locks emitted now stamp `minReaderVersion = version`
+* and cannot be read by orchestrators older than that version — return a
+* one-line heads-up naming the required orchestrator schema. When the floor sits
+* below the current version (`floor < version`) the emitted lock is additive
+* over older readers down to the floor, so no warning is warranted (return
+* null). The orchestrator remains the authoritative reject; this is informational.
+*/
+function schemaWindowWarning(floor, version) {
+	if (floor < version) return null;
+	return `This lock uses schema v${version}, a breaking schema version — orchestrators older than v${version} cannot read it. Upgrade the orchestrator to schema v${version} or newer before it can dispatch from this lock.`;
+}
+/**
 * Detect git repository root by running `git rev-parse --show-toplevel`.
 * Falls back to cwd if not in a git repo.
 *
@@ -96,9 +114,11 @@ function generateLockFile(workflowsWithSource) {
 	});
 	return {
 		schemaVersion: SCHEMA_VERSION$1,
+		minReaderVersion: BREAKING_FLOOR$1,
 		source: topLevelSource,
 		contentHash: sha256(JSON.stringify({
 			schemaVersion: SCHEMA_VERSION$1,
+			minReaderVersion: BREAKING_FLOOR$1,
 			source: topLevelSource,
 			workflows
 		})),
@@ -158,7 +178,7 @@ function transformWorkflow(workflow, sourceFile, exportRef, bundleSource, gitRoo
 			...workflow.concurrency.max !== void 0 && { max: workflow.concurrency.max }
 		} },
 		...workflow.timeout !== void 0 && { timeout: workflow.timeout },
-		...workflow.approval !== void 0 && { approval: (assertNonStepApprovalScope(workflow.approval, "workflow"), toLockApproval(workflow.approval)) }
+		...workflow.approval !== void 0 && { approval: (assertNonStepApprovalScope(workflow.approval, "workflow", locationForWorkflow(sourceFile)), toLockApproval(workflow.approval)) }
 	};
 }
 /**
@@ -316,6 +336,14 @@ function toLockWorkflowComplete(t) {
 		...t.source !== void 0 && { source: t.source }
 	};
 }
+function toLockWorkflowsFailedBatch(t) {
+	return {
+		_type: "workflows_failed_batch",
+		accumulateFor: t.accumulateFor,
+		...t.name !== void 0 && { name: t.name },
+		...t.source !== void 0 && { source: t.source }
+	};
+}
 function toLockJobComplete(t) {
 	return {
 		_type: "job_complete",
@@ -383,6 +411,7 @@ function transformOneTrigger(trigger) {
 		case "WebhookTrigger": return [toLockWebhook(trigger)];
 		case "KiciEventTrigger": return [toLockKiciEvent(trigger)];
 		case "WorkflowCompleteTrigger": return [toLockWorkflowComplete(trigger)];
+		case "WorkflowsFailedBatchTrigger": return [toLockWorkflowsFailedBatch(trigger)];
 		case "JobCompleteTrigger": return [toLockJobComplete(trigger)];
 		case "GenericWebhookTrigger": return [toLockGenericWebhook(trigger)];
 		case "ScheduleTrigger": return [toLockSchedule(trigger)];
@@ -478,11 +507,14 @@ function normalizeRunsOnForLock(runsOn, jobName) {
 * The overlap check compares exact matchers only — a glob/regex include and an
 * exact exclude (or vice versa) cannot be statically known to overlap.
 */
-function validateRunsOn(runsOn, jobName) {
+function validateRunsOn(runsOn, jobName, location) {
 	const { include, exclude } = normalizeRunsOnToMatchers(runsOn, `job '${jobName}' runsOn`);
 	const includeExact = new Set(include.filter((m) => m.kind === "exact").map((m) => m.value));
 	const overlap = exclude.filter((m) => m.kind === "exact").map((m) => m.value).filter((v) => includeExact.has(v));
-	if (overlap.length > 0) throw new Error(`Job "${jobName}": labels and exclude overlap on [${overlap.join(", ")}]. A label cannot be both required and excluded.`);
+	if (overlap.length > 0) throw compilerError("E112", `Job "${jobName}": labels and exclude overlap on [${overlap.join(", ")}]. A label cannot be both required and excluded.`, {
+		location,
+		suggestion: "Remove the overlapping label(s) from either runsOn or the exclude set."
+	});
 }
 /**
 * Transform one context reference (static name or function) into a lock
@@ -490,18 +522,16 @@ function validateRunsOn(runsOn, jobName) {
 * function becomes an inline expression resolvable at two-phase eval; an impure
 * one carries only the `dynamic` flag (the agent runs an init job to resolve it).
 */
-function transformContextRef(ref, jobName) {
+function transformContextRef(ref) {
 	if (typeof ref === "function") {
 		const fnSource = ref.toString();
-		const purity = analyzePurity(fnSource);
-		if (purity.pure) return {
+		if (analyzePurity(fnSource).pure) return {
 			value: {
 				_type: "inline",
 				expression: fnSource
 			},
 			dynamic: true
 		};
-		console.warn(`[kici] Job "${jobName}": context function is not pure (${purity.reason}). An init job will be required, adding ~5-10s delay.`);
 		return {
 			value: "",
 			dynamic: true
@@ -516,15 +546,25 @@ function transformContextRef(ref, jobName) {
 * Transform a static job to lock file format.
 */
 function transformJob(job, configPath, index, gitRoot, uuidToName) {
-	if (job.runsOn !== void 0 && job.runsOnAll !== void 0) throw new Error(`job '${job.name}': runsOn and runsOnAll are mutually exclusive`);
-	if (job.runsOn === void 0 && job.runsOnAll === void 0) throw new Error(`job '${job.name}': one of runsOn or runsOnAll is required`);
+	const jobLocation = locationForJob(job, configPath);
+	if (job.runsOn !== void 0 && job.runsOnAll !== void 0) throw compilerError("E108", `job '${job.name}': runsOn and runsOnAll are mutually exclusive`, {
+		location: jobLocation,
+		suggestion: "Set exactly one of runsOn (single agent) or runsOnAll (fan-out to every matching agent)."
+	});
+	if (job.runsOn === void 0 && job.runsOnAll === void 0) throw compilerError("E109", `job '${job.name}': one of runsOn or runsOnAll is required`, {
+		location: jobLocation,
+		suggestion: "Add runsOn: \"kici:os:linux\" (or another agent label) to the job."
+	});
 	if (job.onUnreachable !== void 0 && job.runsOnAll === void 0) console.warn(`[kici] job '${job.name}': onUnreachable is ignored without runsOnAll`);
-	if (job.maxParallel !== void 0 && job.maxParallel < 1) throw new Error(`job '${job.name}': maxParallel must be >= 1`);
+	if (job.maxParallel !== void 0 && job.maxParallel < 1) throw compilerError("E110", `job '${job.name}': maxParallel must be >= 1`, {
+		location: jobLocation,
+		suggestion: "Set maxParallel to a positive integer, or remove it to run unbounded."
+	});
 	if (!(job.matrix !== void 0 || job.runsOnAll !== void 0) && (job.maxParallel !== void 0 || job.failFast !== void 0)) console.warn(`[kici] job '${job.name}': maxParallel/failFast are ignored without matrix or runsOnAll (no fan-out to bound)`);
-	if (job.runsOn !== void 0) validateRunsOn(job.runsOn, job.name);
+	if (job.runsOn !== void 0) validateRunsOn(job.runsOn, job.name, jobLocation);
 	const contextFields = {};
 	const contextRefs = job.contexts ?? (job.context !== void 0 ? [job.context] : void 0);
-	if (contextRefs !== void 0 && contextRefs.length > 0) contextFields.contexts = contextRefs.map((ref) => transformContextRef(ref, job.name));
+	if (contextRefs !== void 0 && contextRefs.length > 0) contextFields.contexts = contextRefs.map((ref) => transformContextRef(ref));
 	const envFields = {};
 	if (job.env !== void 0) {
 		if (typeof job.env === "function") {
@@ -535,14 +575,16 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 				_type: "inline",
 				expression: fnSource
 			};
-			else console.warn(`[kici] Job "${job.name}": env function is not pure (${purity.reason}). An init job will be required, adding ~5-10s delay.`);
 		} else if (typeof job.env === "object") envFields.env = { ...job.env };
 	}
 	if (job.resources !== void 0) try {
 		validateResourceRequest(job.resources);
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);
-		throw new Error(`Job "${job.name}": invalid resources -- ${reason}`);
+		throw compilerError("E111", `Job "${job.name}": invalid resources -- ${reason}`, {
+			location: jobLocation,
+			suggestion: "Fix the resources request (valid CPU/memory strings, request <= limit)."
+		});
 	}
 	const concurrencyFields = {};
 	if (job.concurrencyGroup !== void 0) {
@@ -554,7 +596,6 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 				_type: "inline",
 				expression: fnSource
 			};
-			else console.warn(`[kici] Job "${job.name}": concurrencyGroup function is not pure (${purity.reason}). An init job will be required, adding ~5-10s delay.`);
 		} else if (typeof job.concurrencyGroup === "string") concurrencyFields.concurrencyGroup = job.concurrencyGroup;
 	}
 	return {
@@ -567,7 +608,7 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		...job.maxParallel !== void 0 && { maxParallel: job.maxParallel },
 		...job.failFast !== void 0 && { failFast: job.failFast },
 		...resolveNeedsForLock(job.needs, uuidToName),
-		steps: transformSteps(job.steps, gitRoot),
+		steps: transformSteps(job.steps, gitRoot, jobLocation),
 		matrix: job.matrix ? transformMatrix(job.matrix, job.name, configPath) : void 0,
 		include: job.include?.map((inc) => ({ ...inc })),
 		exclude: job.exclude?.map((exc) => ({ ...exc })),
@@ -576,6 +617,7 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		...job.checkout !== void 0 && { checkout: job.checkout },
 		...job.cache !== void 0 && { cache: normalizeCacheSpecs(job.cache) },
 		...job.container !== void 0 && { container: job.container },
+		...job.sandbox !== void 0 && { sandbox: job.sandbox },
 		...contextFields,
 		...envFields,
 		...concurrencyFields,
@@ -589,7 +631,7 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		...job.timeout !== void 0 && { timeout: job.timeout },
 		...job.resources !== void 0 && { resources: job.resources },
 		...job.init !== void 0 && { init: job.init },
-		...job.approval !== void 0 && { approval: (assertNonStepApprovalScope(job.approval, "job"), toLockApproval(job.approval)) }
+		...job.approval !== void 0 && { approval: (assertNonStepApprovalScope(job.approval, "job", jobLocation), toLockApproval(job.approval)) }
 	};
 }
 /**
@@ -653,15 +695,21 @@ function toLockApproval(c) {
 * step-scope-only gate (it fires between a step's check and run), so it is a
 * compile error anywhere else.
 */
-function assertNonStepApprovalScope(c, scope) {
-	if (normalizeApproval(c).when === "drift") throw new Error(`approval.when "drift" is only valid on steps (found at ${scope} scope)`);
+function assertNonStepApprovalScope(c, scope, location) {
+	if (normalizeApproval(c).when === "drift") throw compilerError("E113", `approval.when "drift" is only valid on steps (found at ${scope} scope)`, {
+		location,
+		suggestion: "Move the drift-gated approval onto a step, or use when: \"always\" at job/workflow scope."
+	});
 }
 /**
 * Validate a step's approval config: `when: 'drift'` fires between the step's
 * check and run, so it requires a `check` facet. A compile error otherwise.
 */
-function assertStepApprovalCheckFacet(step) {
-	if (step.approval !== void 0 && normalizeApproval(step.approval).when === "drift" && step.check === void 0) throw new Error(`step '${step.name || "(unnamed)"}': approval.when "drift" requires a check facet`);
+function assertStepApprovalCheckFacet(step, jobLocation) {
+	if (step.approval !== void 0 && normalizeApproval(step.approval).when === "drift" && step.check === void 0) throw compilerError("E114", `step '${step.name || "(unnamed)"}': approval.when "drift" requires a check facet`, {
+		location: step._sourceLocation ?? jobLocation,
+		suggestion: "Add a check facet to the step, or use approval when: \"always\"."
+	});
 }
 /**
 * Transform a job's `steps` array into lock-file entries. Sequential steps and
@@ -670,22 +718,40 @@ function assertStepApprovalCheckFacet(step) {
 * compiler's naming matches the agent's `extractAndNormalizeSteps` enumeration —
 * the flat-stepIndex invariant.
 */
-function transformSteps(steps, gitRoot) {
+function transformSteps(steps, gitRoot, jobLocation) {
+	const anchor = jobLocation ?? {
+		file: "",
+		line: 1,
+		column: 1
+	};
 	const counter = { n: 0 };
 	let groupOrdinal = 0;
 	return steps.map((entry) => {
-		if (isParallelGroup(entry)) return transformParallelGroup(entry, gitRoot, counter, groupOrdinal++);
-		return transformSequentialStep(entry, gitRoot, counter);
+		if (isParallelGroup(entry)) return transformParallelGroup(entry, gitRoot, counter, groupOrdinal++, anchor);
+		return transformSequentialStep(entry, gitRoot, counter, anchor);
 	});
 }
+/** Best step-scoped location: the step's captured call-site, else the job anchor. */
+function stepEntryLocation(entry, jobLocation) {
+	return entry._sourceLocation ?? jobLocation;
+}
 /** Validate and transform a `ParallelGroup` into a `LockParallelStep`. */
-function transformParallelGroup(group, gitRoot, counter, groupOrdinal) {
-	if (group.steps.length === 0) throw new Error("job step: empty parallel group not allowed");
+function transformParallelGroup(group, gitRoot, counter, groupOrdinal, jobLocation) {
+	if (group.steps.length === 0) throw compilerError("E115", "job step: empty parallel group not allowed", {
+		location: jobLocation,
+		suggestion: "Add at least one step to the parallel group, or remove the group."
+	});
 	const seen = /* @__PURE__ */ new Set();
 	const children = group.steps.map((child) => {
-		if (isParallelGroup(child)) throw new Error("job step: nested parallel groups are not supported");
-		const lockChild = transformSequentialStep(child, gitRoot, counter);
-		if (seen.has(lockChild.name)) throw new Error(`job step: duplicate step name '${lockChild.name}' in parallel group`);
+		if (isParallelGroup(child)) throw compilerError("E116", "job step: nested parallel groups are not supported", {
+			location: stepEntryLocation(child, jobLocation),
+			suggestion: "Flatten the nested group — a parallel group may only contain steps."
+		});
+		const lockChild = transformSequentialStep(child, gitRoot, counter, jobLocation);
+		if (seen.has(lockChild.name)) throw compilerError("E117", `job step: duplicate step name '${lockChild.name}' in parallel group`, {
+			location: stepEntryLocation(child, jobLocation),
+			suggestion: "Give each step in a parallel group a unique name."
+		});
 		seen.add(lockChild.name);
 		return lockChild;
 	});
@@ -699,7 +765,7 @@ function transformParallelGroup(group, gitRoot, counter, groupOrdinal) {
 	};
 }
 /** Transform a single sequential step (or bare function) into a `LockStep`. */
-function transformSequentialStep(stepOrFn, gitRoot, counter) {
+function transformSequentialStep(stepOrFn, gitRoot, counter, jobLocation) {
 	if (typeof stepOrFn === "function") {
 		counter.n++;
 		return {
@@ -733,7 +799,7 @@ function transformSequentialStep(stepOrFn, gitRoot, counter) {
 		...step.cleanup !== void 0 && { hasCleanup: true },
 		...step.check !== void 0 && { hasCheck: true },
 		...step.whenInSync !== void 0 && { hasWhenInSync: true },
-		...step.approval !== void 0 && { approval: (assertStepApprovalCheckFacet(step), toLockApproval(step.approval)) }
+		...step.approval !== void 0 && { approval: (assertStepApprovalCheckFacet(step, jobLocation), toLockApproval(step.approval)) }
 	};
 }
 /**
@@ -812,6 +878,6 @@ function serializeLockFile(lockFile, pretty = true) {
 	return JSON.stringify(lockFile, null, pretty ? 2 : void 0);
 }
 //#endregion
-export { computeLockfileHash, detectGitRoot, generateLockFile, serializeLockFile, transformSteps, transformTriggers };
+export { computeLockfileHash, detectGitRoot, generateLockFile, schemaWindowWarning, serializeLockFile, transformSteps, transformTriggers };
 
 //# sourceMappingURL=generator.js.map

package/dist/lockfile/index.d.ts

@@ -1,3 +1,5 @@
-export { generateLockFile, serializeLockFile, detectGitRoot, computeLockfileHash, } from './generator.js';
+export { generateLockFile, serializeLockFile, detectGitRoot, computeLockfileHash, schemaWindowWarning, } from './generator.js';
 export { computeContentHash, COMPILE_SCHEMA_VERSION } from './hasher.js';
+export { DynamicValueField, analyzeJobPurity, collectWorkflowPurityWarnings, } from './purity-diagnostics.js';
+export type { JobPurityWarning } from './purity-diagnostics.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/lockfile/index.js

@@ -1,4 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { COMPILE_SCHEMA_VERSION, computeContentHash } from "./hasher.js";
-import { computeLockfileHash, detectGitRoot, generateLockFile, serializeLockFile } from "./generator.js";
-export { COMPILE_SCHEMA_VERSION, computeContentHash, computeLockfileHash, detectGitRoot, generateLockFile, serializeLockFile };
+import { computeLockfileHash, detectGitRoot, generateLockFile, schemaWindowWarning, serializeLockFile } from "./generator.js";
+import { DynamicValueField, analyzeJobPurity, collectWorkflowPurityWarnings } from "./purity-diagnostics.js";
+export { COMPILE_SCHEMA_VERSION, DynamicValueField, analyzeJobPurity, collectWorkflowPurityWarnings, computeContentHash, computeLockfileHash, detectGitRoot, generateLockFile, schemaWindowWarning, serializeLockFile };

package/dist/lockfile/purity-diagnostics.d.ts

@@ -0,0 +1,31 @@
+import type { Job } from '@kici-dev/sdk';
+import type { WorkflowWithSource } from '../types.js';
+/** Which dynamic-value slot on a job carried the impure function. */
+export declare enum DynamicValueField {
+    Context = "context",
+    Env = "env",
+    ConcurrencyGroup = "concurrencyGroup"
+}
+/**
+ * One impure dynamic-value function found on a static job. Each impurity forces
+ * the orchestrator to dispatch an agent-side `__init__` job (~5-10s) instead of
+ * inlining the value, so we surface it to the author at compile / preview time.
+ */
+export interface JobPurityWarning {
+    workflowName: string;
+    sourceFile?: string;
+    jobName: string;
+    field: DynamicValueField;
+    reason: string;
+}
+/**
+ * Analyze a single static job's dynamic-value functions (context(s), env,
+ * concurrencyGroup) for impurity. Returns one warning per impure function.
+ */
+export declare function analyzeJobPurity(job: Job, workflowName: string, sourceFile?: string): JobPurityWarning[];
+/**
+ * Walk every workflow's static jobs and collect impurity warnings. Function-typed
+ * jobs (dynamic job generators) are skipped — their purity is analyzed at dispatch.
+ */
+export declare function collectWorkflowPurityWarnings(workflows: WorkflowWithSource[]): JobPurityWarning[];
+//# sourceMappingURL=purity-diagnostics.d.ts.map

package/dist/lockfile/purity-diagnostics.js

@@ -0,0 +1,52 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { analyzePurity } from "./purity-analyzer.js";
+//#region src/lockfile/purity-diagnostics.ts
+/** Which dynamic-value slot on a job carried the impure function. */
+let DynamicValueField = /* @__PURE__ */ function(DynamicValueField) {
+	DynamicValueField["Context"] = "context";
+	DynamicValueField["Env"] = "env";
+	DynamicValueField["ConcurrencyGroup"] = "concurrencyGroup";
+	return DynamicValueField;
+}({});
+function pushIfImpure(out, fn, field, base) {
+	if (typeof fn !== "function") return;
+	const result = analyzePurity(fn.toString());
+	if (!result.pure) out.push({
+		...base,
+		field,
+		reason: result.reason ?? "unknown"
+	});
+}
+/**
+* Analyze a single static job's dynamic-value functions (context(s), env,
+* concurrencyGroup) for impurity. Returns one warning per impure function.
+*/
+function analyzeJobPurity(job, workflowName, sourceFile) {
+	const out = [];
+	const base = {
+		workflowName,
+		sourceFile,
+		jobName: job.name
+	};
+	const contextRefs = job.contexts ?? (job.context !== void 0 ? [job.context] : void 0);
+	if (contextRefs) for (const ref of contextRefs) pushIfImpure(out, ref, "context", base);
+	pushIfImpure(out, job.env, "env", base);
+	pushIfImpure(out, job.concurrencyGroup, "concurrencyGroup", base);
+	return out;
+}
+/**
+* Walk every workflow's static jobs and collect impurity warnings. Function-typed
+* jobs (dynamic job generators) are skipped — their purity is analyzed at dispatch.
+*/
+function collectWorkflowPurityWarnings(workflows) {
+	const out = [];
+	for (const { workflow, source } of workflows) for (const job of workflow.jobs) {
+		if (typeof job === "function") continue;
+		out.push(...analyzeJobPurity(job, workflow.name, source.file));
+	}
+	return out;
+}
+//#endregion
+export { DynamicValueField, analyzeJobPurity, collectWorkflowPurityWarnings };
+
+//# sourceMappingURL=purity-diagnostics.js.map

package/dist/postinstall.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { readFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { confirm } from "@inquirer/prompts";
+import { isCiEnvironment } from "@kici-dev/core/ci-env";
 //#region src/postinstall.ts
 /**
 * Post-install script for @kici-dev/compiler
@@ -33,7 +34,7 @@ async function detectDevelopmentMode() {
 }
 async function main() {
 	if (await detectDevelopmentMode()) return;
-	if (process.env.CI === "true" || !process.stdout.isTTY) return;
+	if (isCiEnvironment() || !process.stdout.isTTY) return;
 	const fs = await import("node:fs/promises");
 	try {
 		await fs.access(".kici");

package/dist/remote/artifact-extract.d.ts

@@ -0,0 +1,8 @@
+/** Sub-directory of the destination that home-anchored entries land under. */
+export declare const HOME_SUBDIR = "~home";
+/**
+ * Extract an artifact tarball under `destDir`, relocating the anchor groups so
+ * nothing escapes the destination.
+ */
+export declare function extractArtifactTarball(tarball: Buffer, destDir: string): Promise<void>;
+//# sourceMappingURL=artifact-extract.d.ts.map

package/dist/remote/artifact-extract.js

@@ -0,0 +1,58 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { join } from "node:path";
+import { cp, mkdir, readdir } from "node:fs/promises";
+import { HOME_ANCHOR, REPO_ANCHOR } from "@kici-dev/core";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { x } from "tar";
+import { makeTempDir } from "@kici-dev/core/tmp";
+//#region src/remote/artifact-extract.ts
+/**
+* CLI-side artifact extraction.
+*
+* Artifact tarballs are packed by the cache packer, so entries are anchored as
+* `__repo__/<rel>` (repo-root-relative) and `__home__/<rel>` (home-relative).
+* The in-workflow extractor restores those groups to the real repo root / home
+* dir; a CLI must NOT — that would scatter files across the user's filesystem.
+* This helper lands everything under a single destination dir instead:
+*
+*   `__repo__/<rel>` -> `<destDir>/<rel>`
+*   `__home__/<rel>` -> `<destDir>/~home/<rel>`  (kept separate so a
+*                       home-anchored file cannot clobber a repo-anchored one)
+*
+* Extraction goes through a scratch dir first and only relocates on success, so
+* a failed extraction never leaves a half-written output directory.
+*/
+/** Sub-directory of the destination that home-anchored entries land under. */
+const HOME_SUBDIR = "~home";
+/**
+* Extract an artifact tarball under `destDir`, relocating the anchor groups so
+* nothing escapes the destination.
+*/
+async function extractArtifactTarball(tarball, destDir) {
+	const scratch = await makeTempDir("artifact-extract");
+	try {
+		await pipeline(Readable.from(tarball), x({
+			cwd: scratch.path,
+			gzip: true
+		}));
+		await mkdir(destDir, { recursive: true });
+		for (const top of await readdir(scratch.path)) {
+			const from = join(scratch.path, top);
+			if (top === REPO_ANCHOR) await relocateGroup(from, destDir);
+			else if (top === HOME_ANCHOR) await relocateGroup(from, join(destDir, HOME_SUBDIR));
+			else await cp(from, join(destDir, top), { recursive: true });
+		}
+	} finally {
+		await scratch.cleanup();
+	}
+}
+/** Copy the contents of an anchor group dir into `into`, merging trees. */
+async function relocateGroup(groupDir, into) {
+	await mkdir(into, { recursive: true });
+	for (const entry of await readdir(groupDir)) await cp(join(groupDir, entry), join(into, entry), { recursive: true });
+}
+//#endregion
+export { HOME_SUBDIR, extractArtifactTarball };
+
+//# sourceMappingURL=artifact-extract.js.map

package/dist/remote/config.d.ts

@@ -32,13 +32,31 @@ export interface GlobalConfig {
 }
 /**
  * Returns the global KiCI config directory path.
- * Checks KICI_CONFIG_DIR env var first, falls back to ~/.kici.
+ *
+ * Resolution order:
+ *   1. `KICI_CONFIG_DIR`, when set to a non-empty value.
+ *   2. A hard refusal when `KICI_TEST_ISOLATION` is present. A developer
+ *      machine's `~/.kici/config` names a real endpoint and carries a live
+ *      PAT, so a test process that reads it authenticates against whatever
+ *      that config points at — in practice, production. Every test that needs
+ *      a config must name its own isolated directory.
+ *   3. `~/.kici`.
+ *
+ * `KICI_TEST_ISOLATION` is set by this repository's own vitest configs, via
+ * `hack/lib/vitest-isolation.ts`. It is deliberately a KiCI-owned name rather
+ * than the runner's `VITEST`: `kici` is a compat-protected CLI, and `VITEST`
+ * is a third-party marker that propagates into spawned children, so keying off
+ * it would break a customer whose vitest test shells out to `kici`.
+ *
+ * `env` is injectable so this module's own tests can exercise every branch.
+ * It is NOT an opt-out: production call sites pass no argument and inherit the
+ * guard.
  */
-export declare function getConfigDir(): string;
+export declare function getConfigDir(env?: NodeJS.ProcessEnv): string;
 /**
  * Returns the path to the global config file (~/.kici/config).
  */
-export declare function getConfigPath(): string;
+export declare function getConfigPath(env?: NodeJS.ProcessEnv): string;
 /**
  * Load the global KiCI config from ~/.kici/config.
  * Returns an empty object if the file does not exist.

package/dist/remote/config.js

@@ -30,17 +30,36 @@ function sanitizeConfig(raw) {
 }
 /**
 * Returns the global KiCI config directory path.
-* Checks KICI_CONFIG_DIR env var first, falls back to ~/.kici.
+*
+* Resolution order:
+*   1. `KICI_CONFIG_DIR`, when set to a non-empty value.
+*   2. A hard refusal when `KICI_TEST_ISOLATION` is present. A developer
+*      machine's `~/.kici/config` names a real endpoint and carries a live
+*      PAT, so a test process that reads it authenticates against whatever
+*      that config points at — in practice, production. Every test that needs
+*      a config must name its own isolated directory.
+*   3. `~/.kici`.
+*
+* `KICI_TEST_ISOLATION` is set by this repository's own vitest configs, via
+* `hack/lib/vitest-isolation.ts`. It is deliberately a KiCI-owned name rather
+* than the runner's `VITEST`: `kici` is a compat-protected CLI, and `VITEST`
+* is a third-party marker that propagates into spawned children, so keying off
+* it would break a customer whose vitest test shells out to `kici`.
+*
+* `env` is injectable so this module's own tests can exercise every branch.
+* It is NOT an opt-out: production call sites pass no argument and inherit the
+* guard.
 */
-function getConfigDir() {
-	if (process.env.KICI_CONFIG_DIR) return process.env.KICI_CONFIG_DIR;
+function getConfigDir(env = process.env) {
+	if (env.KICI_CONFIG_DIR) return env.KICI_CONFIG_DIR;
+	if (env.KICI_TEST_ISOLATION) throw new Error("Refusing to read the ambient ~/.kici config from a test process. Set KICI_CONFIG_DIR to an isolated directory for this run — the developer machine config may point at production.");
 	return path.join(os.homedir(), ".kici");
 }
 /**
 * Returns the path to the global config file (~/.kici/config).
 */
-function getConfigPath() {
-	return path.join(getConfigDir(), "config");
+function getConfigPath(env = process.env) {
+	return path.join(getConfigDir(env), "config");
 }
 /**
 * Load the global KiCI config from ~/.kici/config.