@kici-dev/compiler 0.0.0 → 0.1.2

package/dist/commands/cancel.js

@@ -0,0 +1,124 @@
+import "../chunk-gOLHoazu.js";
+import { loadGlobalConfig } from "../remote/config.js";
+import pc from "picocolors";
+import { logger, toErrorMessage } from "@kici-dev/shared";
+//#region src/commands/cancel.ts
+/**
+* kici cancel command
+*
+* Cancels a specific run by ID, or all in-progress runs on a branch.
+* Uses the Platform dashboard API (PAT auth) or orchestrator API (direct mode).
+*/
+/**
+* Cancel a run or all runs on a branch.
+*
+* @param runId - Run ID to cancel (optional if --branch is provided)
+* @param options - Cancel options
+* @returns true on success, false on error
+*/
+async function cancelCommand(runId, options = {}) {
+	try {
+		const config = await loadGlobalConfig();
+		const token = config.pat ?? config.token;
+		if (!token) {
+			logger.error(pc.red("Not authenticated. Run `kici login` to get started."));
+			return false;
+		}
+		const endpoint = config.platformEndpoint ?? config.endpoint;
+		if (!endpoint) {
+			logger.error(pc.red("No endpoint configured. Run `kici login` to configure."));
+			return false;
+		}
+		if (options.branch) return await cancelByBranch(endpoint, token, config.activeOrgId, options.branch);
+		if (!runId) {
+			logger.error(pc.red("Please provide a run ID or use --branch to cancel by branch."));
+			return false;
+		}
+		return await cancelRun(endpoint, token, config.activeOrgId, runId, options.force ?? false);
+	} catch (error) {
+		const message = toErrorMessage(error);
+		logger.error(pc.red(`Error: ${message}`));
+		return false;
+	}
+}
+/**
+* Cancel a specific run by ID.
+*/
+async function cancelRun(endpoint, token, orgId, runId, force) {
+	if (!orgId) {
+		logger.error(pc.red("No active organization. Run `kici org use <name>` to set one."));
+		return false;
+	}
+	const action = force ? "Force-cancelling" : "Cancelling";
+	logger.info(`${action} run ${pc.cyan(runId)}...`);
+	const url = `${endpoint}/api/v1/orgs/${orgId}/runs/${runId}/cancel`;
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${token}`
+		},
+		body: JSON.stringify({ force })
+	});
+	if (response.ok) {
+		const jobs = (await response.json()).cancelledJobs ?? 0;
+		logger.info(pc.green(`Run ${runId} cancelled (${jobs} job${jobs !== 1 ? "s" : ""} affected).`));
+		return true;
+	}
+	return handleApiError(response, runId);
+}
+/**
+* Cancel all in-progress runs on a branch.
+*/
+async function cancelByBranch(endpoint, token, orgId, branch) {
+	if (!orgId) {
+		logger.error(pc.red("No active organization. Run `kici org use <name>` to set one."));
+		return false;
+	}
+	logger.info(`Cancelling all in-progress runs on branch ${pc.cyan(branch)}...`);
+	const url = `${endpoint}/api/v1/orgs/${orgId}/runs/cancel-by-branch`;
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${token}`
+		},
+		body: JSON.stringify({ branch })
+	});
+	if (response.ok) {
+		const runs = (await response.json()).cancelledRuns ?? 0;
+		if (runs === 0) logger.info(pc.yellow(`No in-progress runs found on branch ${branch}.`));
+		else logger.info(pc.green(`Cancelled ${runs} run${runs !== 1 ? "s" : ""} on branch ${branch}.`));
+		return true;
+	}
+	return handleApiError(response);
+}
+/**
+* Handle API error responses with clear user-facing messages.
+*/
+async function handleApiError(response, runId) {
+	let errorDetail;
+	try {
+		errorDetail = (await response.json()).error;
+	} catch {}
+	switch (response.status) {
+		case 401:
+			logger.error(pc.red("Authentication failed. Run `kici login` to re-authenticate."));
+			break;
+		case 403:
+			logger.error(pc.red(`Access denied${errorDetail ? `: ${errorDetail}` : ""}.`));
+			break;
+		case 404:
+			logger.error(pc.red(`Run not found${runId ? `: ${runId}` : ""}.`));
+			break;
+		case 409:
+			logger.error(pc.yellow(errorDetail ?? `Run ${runId ?? ""} is already in a terminal state.`));
+			break;
+		default: logger.error(pc.red(errorDetail ?? `Request failed with status ${response.status}.`));
+	}
+	return false;
+}
+//#endregion
+export { cancelCommand };
+
+//# sourceMappingURL=cancel.js.map

package/dist/commands/compile.d.ts

@@ -0,0 +1,17 @@
+/** Options for the compile command */
+export interface CompileOptions {
+    /** Path to .kici directory (defaults to .kici) */
+    kiciDir?: string;
+    /** Validate only, don't write lock file */
+    check: boolean;
+    /** Verbose output */
+    verbose: boolean;
+}
+/**
+ * Execute the compile command.
+ *
+ * @param options - Command options
+ * @returns true if successful, false if errors
+ */
+export declare function compileCommand(options: CompileOptions): Promise<boolean>;
+//# sourceMappingURL=compile.d.ts.map

package/dist/commands/compile.js

@@ -0,0 +1,99 @@
+import "../chunk-gOLHoazu.js";
+import { formatError, isCompilerError } from "../errors/formatter.js";
+import "../errors/index.js";
+import { discoverWorkflows, resolveKiciDir } from "../execution/executor.js";
+import "../execution/index.js";
+import { validateConfig } from "../validation/validator.js";
+import "../validation/index.js";
+import { computeLockfileHash, detectGitRoot, generateLockFile, serializeLockFile } from "../lockfile/generator.js";
+import "../lockfile/index.js";
+import pc from "picocolors";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { logger, toErrorMessage } from "@kici-dev/shared";
+//#region src/commands/compile.ts
+/**
+* Read the existing lock file and return its lockfileHash, if present.
+*/
+async function readExistingLockfileHash(lockPath) {
+	try {
+		const content = await fs.readFile(lockPath, "utf-8");
+		return JSON.parse(content).lockfileHash ?? void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Reinstall dependencies in .kici/ using npm.
+*/
+async function reinstallDeps(kiciDir) {
+	if (existsSync(path.join(kiciDir, "package-lock.json"))) {
+		logger.info("Running " + pc.cyan("npm ci") + ` in ${kiciDir}`);
+		execSync("npm ci", {
+			cwd: kiciDir,
+			stdio: "inherit"
+		});
+	} else {
+		logger.info("Running " + pc.cyan("npm install") + ` in ${kiciDir}`);
+		execSync("npm install", {
+			cwd: kiciDir,
+			stdio: "inherit"
+		});
+	}
+}
+/**
+* Execute the compile command.
+*
+* @param options - Command options
+* @returns true if successful, false if errors
+*/
+async function compileCommand(options) {
+	const kiciDir = options.kiciDir ?? ".kici";
+	const absoluteKiciDir = resolveKiciDir(kiciDir);
+	if (options.verbose) logger.debug(pc.dim(`Discovering workflows from ${absoluteKiciDir}/workflows/...`));
+	try {
+		const lockPath = path.join(absoluteKiciDir, "kici.lock.json");
+		const existingHash = await readExistingLockfileHash(lockPath);
+		if (existingHash) {
+			const currentHash = computeLockfileHash(detectGitRoot());
+			if (currentHash && currentHash !== existingHash) {
+				logger.info(pc.yellow("Dependencies changed") + " — reinstalling before compile...");
+				await reinstallDeps(absoluteKiciDir);
+			}
+		}
+		const { workflows: workflowsWithSource, workflowDir } = await discoverWorkflows(absoluteKiciDir);
+		if (options.verbose) logger.debug(pc.dim(`Found ${workflowsWithSource.length} workflow(s) in ${workflowDir}`));
+		const validation = validateConfig(workflowsWithSource.map((w) => w.workflow), workflowDir);
+		if (!validation.valid) {
+			for (const error of validation.errors) logger.error(formatError(error));
+			return false;
+		}
+		if (options.verbose) logger.debug(pc.dim("Validation passed"));
+		const lockJson = serializeLockFile(generateLockFile(workflowsWithSource));
+		if (!options.check) {
+			await fs.writeFile(lockPath, lockJson, "utf-8");
+			logger.info(pc.green("✓") + ` Compiled workflows → .kici/kici.lock.json` + pc.dim(` (${workflowsWithSource.length} workflow${workflowsWithSource.length !== 1 ? "s" : ""})`));
+			try {
+				const { loadGlobalConfig } = await import("../remote/config.js");
+				const config = await loadGlobalConfig();
+				if (config.token && config.endpoint) {
+					const { typesCommand } = await import("./types.js");
+					await typesCommand({ kiciDir });
+				}
+			} catch {
+				logger.warn(pc.yellow("Could not refresh types (orchestrator unreachable). Compilation succeeded."));
+			}
+		} else logger.info(pc.green("✓") + ` Workflows are valid` + pc.dim(` (${workflowsWithSource.length} workflow${workflowsWithSource.length !== 1 ? "s" : ""})`));
+		return true;
+	} catch (error) {
+		if (isCompilerError(error)) logger.error(formatError(error));
+		else logger.error(pc.red("error") + `: ${toErrorMessage(error)}`);
+		return false;
+	}
+}
+//#endregion
+export { compileCommand };
+
+//# sourceMappingURL=compile.js.map

package/dist/commands/docs.d.ts

@@ -0,0 +1,26 @@
+export interface DocsOptions {
+    /** Open the docs site in the default browser. */
+    open?: boolean;
+}
+export interface DocsLlmOptions {
+    /** Print only the llms.txt index instead of the full markdown bundle. */
+    index?: boolean;
+    /** Override the bundled output destination (overrides default stdout). */
+    out?: string;
+    /** Override the directory holding llms.txt + llms-full.txt (test seam). */
+    bundleDir?: string;
+}
+/**
+ * Open the published documentation site in the user's default browser.
+ */
+export declare function docsCommand(options?: DocsOptions): Promise<boolean>;
+/**
+ * Print the bundled llms.txt or llms-full.txt content to stdout (or a file).
+ *
+ * The bundle is generated at build time by hack/postbuild.mjs and shipped at
+ * dist/llm-context/{llms.txt,llms-full.txt}. Customer-facing LLM tools can
+ * pipe `kici docs llm` straight into an Anthropic / OpenAI context buffer to
+ * brief the agent on KiCI authoring conventions without an internet round-trip.
+ */
+export declare function docsLlmCommand(options?: DocsLlmOptions): Promise<boolean>;
+//# sourceMappingURL=docs.d.ts.map

package/dist/commands/docs.js

@@ -0,0 +1,60 @@
+import "../chunk-gOLHoazu.js";
+import pc from "picocolors";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { logger, toErrorMessage } from "@kici-dev/shared";
+import { fileURLToPath } from "node:url";
+import open from "open";
+//#region src/commands/docs.ts
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DOCS_HOME_URL = "https://kici.dev/docs/";
+/**
+* Open the published documentation site in the user's default browser.
+*/
+async function docsCommand(options = {}) {
+	try {
+		if (options.open === false) {
+			logger.info(DOCS_HOME_URL);
+			return true;
+		}
+		logger.info(pc.gray(`Opening ${DOCS_HOME_URL}`));
+		await open(DOCS_HOME_URL);
+		return true;
+	} catch (error) {
+		logger.error(pc.red(`Error: ${toErrorMessage(error)}`));
+		logger.info(pc.gray(`Visit ${DOCS_HOME_URL} manually.`));
+		return false;
+	}
+}
+/**
+* Print the bundled llms.txt or llms-full.txt content to stdout (or a file).
+*
+* The bundle is generated at build time by hack/postbuild.mjs and shipped at
+* dist/llm-context/{llms.txt,llms-full.txt}. Customer-facing LLM tools can
+* pipe `kici docs llm` straight into an Anthropic / OpenAI context buffer to
+* brief the agent on KiCI authoring conventions without an internet round-trip.
+*/
+async function docsLlmCommand(options = {}) {
+	const filename = options.index ? "llms.txt" : "llms-full.txt";
+	const bundleDir = options.bundleDir ?? path.join(__dirname, "..", "llm-context");
+	const bundlePath = path.join(bundleDir, filename);
+	try {
+		const content = await readFile(bundlePath, "utf-8");
+		if (options.out) {
+			await writeFile(options.out, content, "utf-8");
+			logger.info(pc.gray(`Wrote ${filename} to ${options.out}`));
+			return true;
+		}
+		process.stdout.write(content);
+		if (!content.endsWith("\n")) process.stdout.write("\n");
+		return true;
+	} catch (error) {
+		logger.error(pc.red(`Error reading bundled ${filename}: ${toErrorMessage(error)}`));
+		logger.info(pc.gray("The bundle ships with the @kici-dev/compiler package. If you built the package locally, run `pnpm build` in packages/compiler/."));
+		return false;
+	}
+}
+//#endregion
+export { docsCommand, docsLlmCommand };
+
+//# sourceMappingURL=docs.js.map

package/dist/commands/drain-worker.d.ts

@@ -0,0 +1,19 @@
+/**
+ * kici admin drain-worker command
+ *
+ * Sends POST /drain to a worker instance to trigger graceful drain.
+ * Part of the three drain mechanisms: SIGTERM, POST /drain, admin CLI.
+ */
+/** Options for the drain-worker command */
+export interface DrainWorkerOptions {
+    /** Worker URL (e.g., http://worker-host:<port>) */
+    url: string;
+}
+/**
+ * Send a drain request to a worker instance.
+ *
+ * @param options - Drain worker options
+ * @returns true on success, false on error
+ */
+export declare function drainWorkerCommand(options: DrainWorkerOptions): Promise<boolean>;
+//# sourceMappingURL=drain-worker.d.ts.map

package/dist/commands/drain-worker.js

@@ -0,0 +1,45 @@
+import "../chunk-gOLHoazu.js";
+import pc from "picocolors";
+import { logger, toErrorMessage } from "@kici-dev/shared";
+//#region src/commands/drain-worker.ts
+/**
+* kici admin drain-worker command
+*
+* Sends POST /drain to a worker instance to trigger graceful drain.
+* Part of the three drain mechanisms: SIGTERM, POST /drain, admin CLI.
+*/
+/**
+* Send a drain request to a worker instance.
+*
+* @param options - Drain worker options
+* @returns true on success, false on error
+*/
+async function drainWorkerCommand(options) {
+	const { url } = options;
+	if (!url) {
+		logger.error(pc.red("--url is required. Specify the worker URL (e.g., http://worker-host:<port>)."));
+		return false;
+	}
+	try {
+		const drainUrl = `${url.replace(/\/$/, "")}/drain`;
+		const response = await fetch(drainUrl, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" }
+		});
+		if (!response.ok) {
+			logger.error(pc.red(`Drain request failed: ${response.status} ${response.statusText}`));
+			return false;
+		}
+		const data = await response.json();
+		logger.info(pc.green(`Worker draining. Active jobs: ${data.activeJobs}`));
+		return true;
+	} catch (error) {
+		const message = toErrorMessage(error);
+		logger.error(pc.red(`Failed to connect to worker at ${url}: ${message}`));
+		return false;
+	}
+}
+//#endregion
+export { drainWorkerCommand };
+
+//# sourceMappingURL=drain-worker.js.map

package/dist/commands/endpoints.d.ts

@@ -0,0 +1,53 @@
+/**
+ * kici endpoints command
+ *
+ * Lists all webhook entrypoints for the current project, grouped by type.
+ * Reads the compiled lock file to enumerate trigger types and displays
+ * webhook URLs that developers can paste into external service configurations.
+ */
+import type { LockWorkflow } from '../types.js';
+export interface EndpointsOptions {
+    /** Path to .kici directory (defaults to .kici) */
+    kiciDir?: string;
+}
+interface TriggerGroup {
+    gitProvider: Array<{
+        workflowName: string;
+        provider: string;
+    }>;
+    genericWebhook: Array<{
+        workflowName: string;
+        source: string;
+        path?: string;
+    }>;
+    schedule: Array<{
+        workflowName: string;
+        cron: string;
+        timezone: string;
+        description?: string;
+    }>;
+    lifecycle: Array<{
+        workflowName: string;
+        events: readonly string[];
+        description?: string;
+    }>;
+    kiciEvent: Array<{
+        workflowName: string;
+        eventName: string;
+    }>;
+}
+/**
+ * Main endpoints command entry point.
+ * Reads the lock file and displays all webhook entrypoints grouped by type.
+ */
+export declare function endpointsCommand(options: EndpointsOptions): Promise<boolean>;
+/**
+ * Group all workflow triggers by their type category.
+ */
+export declare function groupTriggers(workflows: readonly LockWorkflow[]): TriggerGroup;
+/**
+ * Display the grouped endpoints in a human-readable format.
+ */
+export declare function displayEndpoints(groups: TriggerGroup, orgId: string): void;
+export {};
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/commands/endpoints.js

@@ -0,0 +1,185 @@
+import "../chunk-gOLHoazu.js";
+import { resolveKiciDir } from "../execution/executor.js";
+import "../execution/index.js";
+import { loadGlobalConfig } from "../remote/config.js";
+import pc from "picocolors";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { logger, toErrorMessage } from "@kici-dev/shared";
+//#region src/commands/endpoints.ts
+/**
+* kici endpoints command
+*
+* Lists all webhook entrypoints for the current project, grouped by type.
+* Reads the compiled lock file to enumerate trigger types and displays
+* webhook URLs that developers can paste into external service configurations.
+*/
+/**
+* Main endpoints command entry point.
+* Reads the lock file and displays all webhook entrypoints grouped by type.
+*/
+async function endpointsCommand(options) {
+	try {
+		const kiciDir = resolveKiciDir(options.kiciDir);
+		const lockFilePath = path.join(kiciDir, "kici.lock.json");
+		let lockFile;
+		try {
+			const content = await readFile(lockFilePath, "utf-8");
+			lockFile = JSON.parse(content);
+		} catch {
+			logger.error(pc.red("No lock file found. Run `kici compile` to generate kici.lock.json first."));
+			return false;
+		}
+		const orgId = (await loadGlobalConfig()).activeOrgId ?? "{orgId}";
+		displayEndpoints(groupTriggers(lockFile.workflows), orgId);
+		return true;
+	} catch (error) {
+		const message = toErrorMessage(error);
+		logger.error(pc.red(`Error: ${message}`));
+		return false;
+	}
+}
+/**
+* Group all workflow triggers by their type category.
+*/
+function groupTriggers(workflows) {
+	const groups = {
+		gitProvider: [],
+		genericWebhook: [],
+		schedule: [],
+		lifecycle: [],
+		kiciEvent: []
+	};
+	for (const workflow of workflows) for (const trigger of workflow.triggers) categorizeTrigger(workflow.name, trigger, groups);
+	return groups;
+}
+/**
+* Categorize a single trigger into the appropriate group.
+*/
+function categorizeTrigger(workflowName, trigger, groups) {
+	switch (trigger._type) {
+		case "pr":
+		case "push":
+		case "tag":
+		case "comment":
+		case "review":
+		case "review_comment":
+		case "release":
+		case "dispatch":
+		case "create":
+		case "delete":
+		case "status":
+		case "workflow_run":
+		case "fork":
+		case "star":
+		case "watch":
+		case "webhook":
+			if (!groups.gitProvider.some((g) => g.workflowName === workflowName)) groups.gitProvider.push({
+				workflowName,
+				provider: "GitHub"
+			});
+			break;
+		case "generic_webhook":
+			groups.genericWebhook.push({
+				workflowName,
+				source: trigger.source,
+				path: trigger.path
+			});
+			break;
+		case "schedule":
+			groups.schedule.push({
+				workflowName,
+				cron: trigger.cronExpression,
+				timezone: trigger.timezone,
+				description: trigger.description
+			});
+			break;
+		case "lifecycle":
+			groups.lifecycle.push({
+				workflowName,
+				events: trigger.events,
+				description: trigger.description
+			});
+			break;
+		case "kici_event":
+			groups.kiciEvent.push({
+				workflowName,
+				eventName: trigger.eventName
+			});
+			break;
+		case "workflow_complete":
+			groups.kiciEvent.push({
+				workflowName,
+				eventName: `workflow_complete${trigger.name ? `:${trigger.name}` : ""}`
+			});
+			break;
+		case "job_complete":
+			groups.kiciEvent.push({
+				workflowName,
+				eventName: `job_complete${trigger.workflow ? `:${trigger.workflow}` : ""}${trigger.job ? `.${trigger.job}` : ""}`
+			});
+			break;
+	}
+}
+/**
+* Display the grouped endpoints in a human-readable format.
+*/
+function displayEndpoints(groups, orgId) {
+	let hasOutput = false;
+	let hasWebhookUrls = false;
+	if (groups.gitProvider.length > 0) {
+		hasOutput = true;
+		hasWebhookUrls = true;
+		logger.info(pc.bold("\nGit provider webhooks:"));
+		const providers = [...new Set(groups.gitProvider.map((g) => g.provider))];
+		for (const provider of providers) {
+			const urlPath = `/webhook/${orgId}/${provider.toLowerCase()}`;
+			logger.info(`  ${pc.cyan(provider + ":")}  ${urlPath}`);
+		}
+	}
+	if (groups.genericWebhook.length > 0) {
+		hasOutput = true;
+		hasWebhookUrls = true;
+		logger.info(pc.bold("\nGeneric webhooks:"));
+		const seen = /* @__PURE__ */ new Set();
+		for (const gw of groups.genericWebhook) {
+			if (seen.has(gw.source)) continue;
+			seen.add(gw.source);
+			const urlPath = `/webhook/${orgId}/generic/${gw.source}`;
+			logger.info(`  ${pc.cyan((gw.source + ":").padEnd(16))} ${urlPath}`);
+		}
+	}
+	if (groups.schedule.length > 0) {
+		hasOutput = true;
+		logger.info(pc.bold("\nScheduled workflows:"));
+		for (const s of groups.schedule) {
+			const tz = s.timezone !== "UTC" ? ` (${s.timezone})` : " (UTC)";
+			const label = s.description ?? s.workflowName;
+			logger.info(`  ${pc.cyan((label + ":").padEnd(24))} "${s.cron}"${tz}`);
+		}
+	}
+	const eventDriven = [...groups.lifecycle.map((l) => ({
+		workflowName: l.workflowName,
+		description: l.description ?? l.workflowName,
+		listensFor: `lifecycle (${l.events.join(", ")})`
+	})), ...groups.kiciEvent.map((k) => ({
+		workflowName: k.workflowName,
+		description: k.workflowName,
+		listensFor: `kici_event (${k.eventName})`
+	}))];
+	if (eventDriven.length > 0) {
+		hasOutput = true;
+		logger.info(pc.bold("\nEvent-driven workflows:"));
+		for (const e of eventDriven) logger.info(`  ${pc.cyan((e.description + ":").padEnd(24))} listens for: ${e.listensFor}`);
+	}
+	if (!hasOutput) {
+		logger.info(pc.yellow("\nNo webhook entrypoints found in the lock file."));
+		logger.info(pc.gray("Add triggers to your workflows and run `kici compile` to generate endpoints."));
+	}
+	if (hasWebhookUrls && orgId === "{orgId}") logger.info(pc.gray("\nHint: Run `kici login` and `kici org use <name>` to resolve the {orgId} placeholder."));
+	logger.info("");
+}
+//#endregion
+export { displayEndpoints, endpointsCommand, groupTriggers };
+
+//# sourceMappingURL=endpoints.js.map

package/dist/commands/fixture.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Fixture generation command
+ *
+ * Generates JSON fixture templates for all supported event types,
+ * including internal events (schedule, lifecycle, generic_webhook, kici_event).
+ */
+export interface FixtureOptions {
+    output?: string;
+}
+/**
+ * Generate fixture template for event type
+ */
+export declare function fixtureCommand(event: string, options: FixtureOptions): Promise<void>;
+//# sourceMappingURL=fixture.d.ts.map