@kici-dev/compiler 0.0.0 → 0.1.1

package/dist/local-executor/picker.js

@@ -0,0 +1,109 @@
+import "../chunk-gOLHoazu.js";
+import { transformTriggers } from "../lockfile/generator.js";
+import { parseEventArg, triggerSummary, triggerToEventArg } from "../test-runner/event-types.js";
+import pc from "picocolors";
+import { logger } from "@kici-dev/shared";
+import { select } from "@inquirer/prompts";
+//#region src/local-executor/picker.ts
+/**
+* Interactive workflow picker for `kici run local --pick`.
+*
+* Lists every workflow with a summary of its triggers, lets the user pick one
+* (and a specific trigger when there are multiple), and returns the derived
+* event arg plus workflow name. The caller feeds these back into the standard
+* executeLocal pipeline so the run remains consistent with normal trigger
+* matching.
+*/
+var PickerCancelledError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PickerCancelledError";
+	}
+};
+function workflowEntries(workflows) {
+	return workflows.map((w) => ({
+		name: w.name,
+		triggers: transformTriggers(w.on)
+	}));
+}
+function eventFamily(arg) {
+	return arg.toLowerCase().split(":")[0] ?? "";
+}
+function filterFamily(arg) {
+	try {
+		const parsed = parseEventArg(arg);
+		if (parsed.type === "pull_request") return "pr";
+		return parsed.type;
+	} catch {
+		return eventFamily(arg);
+	}
+}
+function triggerFamilies(trigger) {
+	const head = eventFamily(triggerToEventArg(trigger));
+	if (trigger._type === "generic_webhook") return ["webhook", "generic_webhook"];
+	if (trigger._type === "workflow_complete") return [head, "lifecycle"];
+	if (trigger._type === "job_complete") return [head, "lifecycle"];
+	return [head];
+}
+function isStdinTty() {
+	return Boolean(process.stdin.isTTY);
+}
+function printWorkflowList(entries) {
+	logger.info(pc.bold("Available workflows:"));
+	for (const entry of entries) {
+		const summaries = entry.triggers.map(triggerSummary).join(", ") || "(no triggers)";
+		logger.info(`  ${pc.cyan(entry.name)} — ${summaries}`);
+	}
+}
+/**
+* Run the interactive picker.
+*
+* @throws PickerCancelledError when stdin is not a TTY, when no eligible
+*   workflows exist, or when the user aborts one of the prompts.
+*/
+async function runPicker(workflows, opts = {}) {
+	let entries = workflowEntries(workflows).filter((e) => e.triggers.length > 0);
+	if (opts.filterEvent) {
+		const family = filterFamily(opts.filterEvent);
+		entries = entries.filter((e) => e.triggers.some((t) => triggerFamilies(t).includes(family)));
+	}
+	if (entries.length === 0) throw new PickerCancelledError(opts.filterEvent ? `No workflows with triggers matching "${opts.filterEvent}". Remove the event arg or pass a different one.` : "No workflows with triggers available to pick.");
+	if (!isStdinTty()) {
+		printWorkflowList(entries);
+		throw new PickerCancelledError("Non-interactive environment: --pick requires a TTY. Pass --workflow <name> plus an event arg instead.");
+	}
+	let chosenWorkflow;
+	try {
+		const name = await select({
+			message: "Select a workflow to run",
+			choices: entries.map((e) => ({
+				name: `${e.name} — ${e.triggers.map(triggerSummary).join(", ")}`,
+				value: e.name
+			}))
+		});
+		chosenWorkflow = entries.find((e) => e.name === name);
+	} catch (err) {
+		throw new PickerCancelledError(`Picker cancelled: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	let trigger;
+	if (chosenWorkflow.triggers.length === 1) trigger = chosenWorkflow.triggers[0];
+	else try {
+		trigger = await select({
+			message: `Select a trigger for "${chosenWorkflow.name}"`,
+			choices: chosenWorkflow.triggers.map((t) => ({
+				name: triggerSummary(t),
+				value: t
+			}))
+		});
+	} catch (err) {
+		throw new PickerCancelledError(`Picker cancelled: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return {
+		event: triggerToEventArg(trigger),
+		workflow: chosenWorkflow.name
+	};
+}
+//#endregion
+export { PickerCancelledError, runPicker };
+
+//# sourceMappingURL=picker.js.map

package/dist/local-executor/secret-loader.d.ts

@@ -0,0 +1,18 @@
+import type { ParsedSecrets } from '../test-runner/secrets-file.js';
+/**
+ * Load secrets from multiple sources with merge precedence.
+ *
+ * Merge order (lowest to highest priority):
+ * 1. .kici/.secrets (INI-style, backward compat)
+ * 2. .kici/.env.local (dotenv format)
+ * 3. .kici/secrets.yaml (YAML with environment scopes, merged flat)
+ * 4. --env KEY=VALUE CLI flags
+ *
+ * Note: process.env is NOT merged here -- it's handled at step-context level.
+ *
+ * @param kiciDir - Path to the .kici directory
+ * @param envFlags - Optional --env KEY=VALUE flag values
+ * @returns Merged secrets with correct precedence
+ */
+export declare function loadLocalSecrets(kiciDir: string, envFlags?: string[]): Promise<ParsedSecrets>;
+//# sourceMappingURL=secret-loader.d.ts.map

package/dist/local-executor/secret-loader.js

@@ -0,0 +1,105 @@
+import "../chunk-gOLHoazu.js";
+import { loadSecretsFile } from "../test-runner/secrets-file.js";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parse } from "yaml";
+//#region src/local-executor/secret-loader.ts
+/**
+* Parse a dotenv-style file (.env.local) into flat key-value pairs.
+* Lines starting with # are comments. Blank lines are ignored.
+*/
+function parseDotenv(content) {
+	const result = {};
+	for (const rawLine of content.split("\n")) {
+		const line = rawLine.trim();
+		if (line === "" || line.startsWith("#")) continue;
+		const eqIndex = line.indexOf("=");
+		if (eqIndex === -1) continue;
+		const key = line.slice(0, eqIndex).trim();
+		let value = line.slice(eqIndex + 1).trim();
+		if (value.length >= 2 && (value[0] === "\"" && value[value.length - 1] === "\"" || value[0] === "'" && value[value.length - 1] === "'")) value = value.slice(1, -1);
+		result[key] = value;
+	}
+	return result;
+}
+/**
+* Parse a secrets.yaml file.
+* Expected format: top-level keys are environment names, values are key-value maps.
+* For local execution, all environments are merged flat (no environment resolution).
+*/
+function parseSecretsYaml(content) {
+	const parsed = parse(content);
+	if (!parsed || typeof parsed !== "object") return {};
+	const result = {};
+	for (const [, envSecrets] of Object.entries(parsed)) if (envSecrets && typeof envSecrets === "object" && !Array.isArray(envSecrets)) {
+		for (const [key, value] of Object.entries(envSecrets)) if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") result[key] = String(value);
+	}
+	return result;
+}
+/**
+* Parse --env KEY=VALUE flags into a flat map.
+*/
+function parseEnvFlags(flags) {
+	const result = {};
+	for (const flag of flags) {
+		const eqIndex = flag.indexOf("=");
+		if (eqIndex === -1) continue;
+		const key = flag.slice(0, eqIndex).trim();
+		result[key] = flag.slice(eqIndex + 1);
+	}
+	return result;
+}
+/**
+* Read a file, returning null if it doesn't exist.
+*/
+async function readFileOrNull(filePath) {
+	try {
+		return await readFile(filePath, "utf-8");
+	} catch (err) {
+		if (err instanceof Error && "code" in err && err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+/**
+* Load secrets from multiple sources with merge precedence.
+*
+* Merge order (lowest to highest priority):
+* 1. .kici/.secrets (INI-style, backward compat)
+* 2. .kici/.env.local (dotenv format)
+* 3. .kici/secrets.yaml (YAML with environment scopes, merged flat)
+* 4. --env KEY=VALUE CLI flags
+*
+* Note: process.env is NOT merged here -- it's handled at step-context level.
+*
+* @param kiciDir - Path to the .kici directory
+* @param envFlags - Optional --env KEY=VALUE flag values
+* @returns Merged secrets with correct precedence
+*/
+async function loadLocalSecrets(kiciDir, envFlags) {
+	const iniSecrets = await loadSecretsFile(kiciDir);
+	const flat = { ...iniSecrets.flat };
+	const contexts = {};
+	for (const [ctx, vals] of Object.entries(iniSecrets.contexts)) contexts[ctx] = { ...vals };
+	const envLocalContent = await readFileOrNull(path.join(kiciDir, ".env.local"));
+	if (envLocalContent !== null) {
+		const envLocalSecrets = parseDotenv(envLocalContent);
+		Object.assign(flat, envLocalSecrets);
+	}
+	const yamlContent = await readFileOrNull(path.join(kiciDir, "secrets.yaml"));
+	if (yamlContent !== null) {
+		const yamlSecrets = parseSecretsYaml(yamlContent);
+		Object.assign(flat, yamlSecrets);
+	}
+	if (envFlags && envFlags.length > 0) {
+		const flagSecrets = parseEnvFlags(envFlags);
+		Object.assign(flat, flagSecrets);
+	}
+	return {
+		flat,
+		contexts
+	};
+}
+//#endregion
+export { loadLocalSecrets };
+
+//# sourceMappingURL=secret-loader.js.map

package/dist/local-executor/types.d.ts

@@ -0,0 +1,80 @@
+import type { MatrixValues, Job } from '@kici-dev/sdk';
+import type { JobResult } from '../test-runner/job-executor.js';
+/**
+ * All CLI flags for `kici run local`.
+ */
+export interface RunLocalOptions {
+    /** Positional arg: event type (e.g. 'push', 'pr:open'). Optional when `pick` is true. */
+    event?: string;
+    /** --pick / -p: interactive workflow picker (derives event arg from the selected trigger) */
+    pick?: boolean;
+    /** --workflow filter: run only matching workflow */
+    workflow?: string;
+    /** --job filter: run only matching job (includes transitive deps) */
+    job?: string;
+    /** --branch override: override detected git branch */
+    branch?: string;
+    /** --sha override: override detected git SHA */
+    sha?: string;
+    /** --payload path: explicit event payload JSON file */
+    payload?: string;
+    /** --concurrency: max parallel jobs (default: os.availableParallelism()) */
+    concurrency?: number;
+    /** --keep-going: continue after job failure (default: false) */
+    keepGoing?: boolean;
+    /** --container: use Podman isolation (default: false) */
+    container?: boolean;
+    /** --env KEY=VALUE overrides (repeatable) */
+    env?: string[];
+    /** --quiet: minimal output */
+    quiet?: boolean;
+    /** --json: JSON output format */
+    json?: boolean;
+    /** --junit: path for JUnit XML report */
+    junit?: string;
+    /** --files: override changed file paths (repeatable) */
+    files?: string[];
+    /** --debug: verbose debug output */
+    debug?: boolean;
+    /** --kici-dir: path to .kici directory */
+    kiciDir?: string;
+}
+/**
+ * A job after matrix expansion with resolved values.
+ */
+export interface ResolvedJob {
+    /** Original job definition */
+    job: Job;
+    /** Expanded name (e.g. 'test (node-18, linux)') */
+    expandedName: string;
+    /** Matrix values for this expansion (empty object if no matrix) */
+    matrixValues: MatrixValues;
+    /** Resolved dependency names (expanded names of upstream jobs) */
+    resolvedNeeds: string[];
+}
+/**
+ * Result for a single job execution in local mode.
+ * Extends JobResult with matrix context and cancellation.
+ */
+export interface LocalJobResult extends Omit<JobResult, 'status'> {
+    /** Job completion status (adds 'cancelled' to base JobResult statuses) */
+    status: 'success' | 'failure' | 'skipped' | 'cancelled';
+    /** Matrix values if this job was part of a matrix expansion */
+    matrixValues?: MatrixValues;
+    /** Whether this job was cancelled (e.g. by AbortSignal) */
+    cancelled?: boolean;
+}
+/**
+ * Result of executing a workflow locally.
+ */
+export interface WorkflowExecutionResult {
+    /** Workflow name */
+    name: string;
+    /** Overall status */
+    status: 'success' | 'failure' | 'skipped';
+    /** Individual job results */
+    jobs: LocalJobResult[];
+    /** Total execution duration in milliseconds */
+    durationMs: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/local-executor/types.js

@@ -0,0 +1,2 @@
+import "../chunk-gOLHoazu.js";
+export {};

package/dist/local-executor/workflow-lock.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Workflow-level concurrency lock for `kici run local`.
+ *
+ * Enforces the SDK-declared `workflow.concurrency` block across concurrent
+ * `kici run local` invocations on the same machine and user. Mirrors the
+ * orchestrator semantics:
+ *
+ * - `group` callback evaluated against the simulated event, fails closed
+ *   on throw via {@link ConcurrencyKeyEvaluationError} (the caller aborts the
+ *   run rather than fall back to the workflow name).
+ * - `cancelInProgress: true` interrupts the holder via SIGTERM, escalates
+ *   to SIGKILL after `KICI_LOCAL_LOCK_KILL_GRACE_MS` (default 30000ms).
+ * - Otherwise contention waits in FIFO order on the underlying file lock.
+ * - Stale locks (holder PID gone per `process.kill(pid, 0)`) are reclaimed.
+ *
+ * The lock primitive is `proper-lockfile` (atomic `mkdir` of a `.lock`
+ * directory next to the metadata sidecar). The lock identity is
+ * `sha256(workflowName + '\0' + groupKey)`, scoped to a per-user lock dir
+ * (`$XDG_RUNTIME_DIR/kici-local-locks/` on Linux, else
+ * `os.tmpdir()/kici-local-locks-<uid>/`).
+ */
+import type { Workflow } from '@kici-dev/sdk';
+/** Sidecar metadata persisted next to the lock dir for diagnostics + reclamation. */
+export interface LockHolderMetadata {
+    pid: number;
+    startedAt: string;
+    workflowName: string;
+    groupKey: string;
+    hostname: string;
+}
+/** Handle returned by {@link acquireWorkflowLock}. Caller MUST invoke `release()` in a `finally`. */
+export interface WorkflowLockHandle {
+    release(): Promise<void>;
+}
+export interface AcquireWorkflowLockOptions {
+    workflowName: string;
+    workflow: Workflow;
+    /** The simulated-event payload object passed as `groupCtx.event` to the user's group fn. */
+    event: Record<string, unknown>;
+    /** Branch derived from the simulated event for `groupCtx.branch`. */
+    branch: string;
+    debug?: boolean;
+}
+/**
+ * Thrown when the workflow's `concurrency.group()` function throws or rejects.
+ * The caller surfaces this as a workflow failure (it does NOT fall back to the
+ * workflow name as a key — fail-closed is the documented contract).
+ */
+export declare class ConcurrencyKeyEvaluationError extends Error {
+    readonly cause?: Error;
+    readonly workflowName: string;
+    constructor(workflowName: string, cause: unknown);
+}
+/** Module-level stub for `process.kill`, swappable by tests via {@link __setKillFnForTesting}. */
+type KillFn = (pid: number, signal?: string | number) => boolean;
+/** Test-only: swap the kill function so unit tests don't actually signal real PIDs. */
+export declare function __setKillFnForTesting(fn?: KillFn): void;
+/**
+ * Resolve the per-user lock directory. Prefers `$XDG_RUNTIME_DIR/kici-local-locks/`
+ * (Linux per-user runtime dir, mode 0700), else `os.tmpdir()/kici-local-locks-<uid>/`.
+ *
+ * Created with `mode: 0o700`. Falls through silently to the tmpdir form on EACCES/EROFS.
+ */
+export declare function resolveLockDir(): Promise<string>;
+/**
+ * Evaluate the workflow's concurrency `group` function against the simulated event.
+ *
+ * Returns `null` when the workflow has no `concurrency` block. Throws
+ * {@link ConcurrencyKeyEvaluationError} when the group function throws or rejects.
+ */
+export declare function resolveConcurrencyKey(workflow: Workflow, event: Record<string, unknown>, branch: string): Promise<string | null>;
+/**
+ * Acquire the workflow-level concurrency lock for a `kici run local` invocation.
+ *
+ * Returns `null` immediately when the workflow has no `concurrency` block (no
+ * locking is performed). Otherwise blocks until the lock is held, then returns
+ * a handle whose `release()` MUST be invoked in a `finally`.
+ */
+export declare function acquireWorkflowLock(opts: AcquireWorkflowLockOptions): Promise<WorkflowLockHandle | null>;
+export {};
+//# sourceMappingURL=workflow-lock.d.ts.map

package/dist/lockfile/generator.d.ts

@@ -0,0 +1,39 @@
+import type { TriggerConfig } from '@kici-dev/sdk';
+import { type LockFile, type LockTrigger, type WorkflowWithSource } from '../types.js';
+/**
+ * Detect git repository root by running `git rev-parse --show-toplevel`.
+ * Falls back to cwd if not in a git repo.
+ *
+ * @returns Absolute path to git root, or cwd if not in git repo
+ */
+export declare function detectGitRoot(): string;
+/**
+ * Compute SHA-256 hash of the .kici/package-lock.json lockfile.
+ * Used as part of the dependency cache key.
+ *
+ * @param gitRoot - Absolute path to git repository root
+ * @returns Hex SHA-256 hash string, or null if no lockfile found in .kici/
+ */
+export declare function computeLockfileHash(gitRoot: string): string | null;
+/**
+ * Generate a lock file from validated workflows with source tracking.
+ *
+ * @param workflowsWithSource - Validated workflows with source info
+ * @returns Lock file ready for JSON serialization
+ */
+export declare function generateLockFile(workflowsWithSource: WorkflowWithSource[]): LockFile;
+/**
+ * Transform trigger configs to lock file format.
+ * Uses flatMap because push triggers with tags generate two lock triggers.
+ * Exported for reuse in the test runner's in-memory lock format conversion.
+ */
+export declare function transformTriggers(triggers?: TriggerConfig[]): readonly LockTrigger[];
+/**
+ * Serialize lock file to JSON string.
+ *
+ * @param lockFile - Lock file object
+ * @param pretty - Whether to pretty-print (default: true)
+ * @returns JSON string
+ */
+export declare function serializeLockFile(lockFile: LockFile, pretty?: boolean): string;
+//# sourceMappingURL=generator.d.ts.map