@kici-dev/compiler 0.0.0 → 0.1.1

package/dist/generators/secrets-dts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * .d.ts generator for environment secret type augmentation.
+ *
+ * Produces a TypeScript declaration file that augments @kici-dev/sdk's
+ * KnownSecretKeys and EnvironmentSecrets interfaces, enabling compile-time
+ * autocomplete and type checking for `ctx.secrets.get()` and `ctx.secrets.expose()`
+ * key names per environment.
+ */
+export interface EnvironmentMetadata {
+    name: string;
+    keys: string[];
+}
+interface GenerateSecretsDtsOptions {
+    environments: EnvironmentMetadata[];
+    endpoint: string;
+    generatedAt: Date;
+}
+/**
+ * Generate a .d.ts string from environment metadata.
+ *
+ * The output augments @kici-dev/sdk's KnownSecretKeys and EnvironmentSecrets
+ * interfaces, enabling compile-time autocomplete for secret keys per environment.
+ *
+ * @param options - Environment metadata, endpoint URL, and generation timestamp
+ * @returns The .d.ts file content as a string
+ */
+export declare function generateSecretsDts(options: GenerateSecretsDtsOptions): string;
+export {};
+//# sourceMappingURL=secrets-dts.d.ts.map

package/dist/generators/secrets-dts.js

@@ -0,0 +1,67 @@
+import "../chunk-gOLHoazu.js";
+//#region src/generators/secrets-dts.ts
+/**
+* Check if a string is a valid TypeScript identifier (unquoted property name).
+*/
+function isValidIdentifier(name) {
+	return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
+}
+function escapeQuotes(s) {
+	return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+function formatProperty(name) {
+	return isValidIdentifier(name) ? name : `'${escapeQuotes(name)}'`;
+}
+/**
+* Build a map of key -> list of environment names that provide it.
+*/
+function buildKeySourceMap(environments) {
+	const map = /* @__PURE__ */ new Map();
+	for (const env of environments) for (const key of env.keys) {
+		const sources = map.get(key);
+		if (sources) sources.push(env.name);
+		else map.set(key, [env.name]);
+	}
+	return map;
+}
+/**
+* Generate a .d.ts string from environment metadata.
+*
+* The output augments @kici-dev/sdk's KnownSecretKeys and EnvironmentSecrets
+* interfaces, enabling compile-time autocomplete for secret keys per environment.
+*
+* @param options - Environment metadata, endpoint URL, and generation timestamp
+* @returns The .d.ts file content as a string
+*/
+function generateSecretsDts(options) {
+	const { environments, endpoint, generatedAt } = options;
+	const lines = [];
+	lines.push("// @generated by kici types -- DO NOT EDIT");
+	lines.push(`// Orchestrator: ${endpoint}`);
+	lines.push(`// Generated: ${generatedAt.toISOString()}`);
+	lines.push("// Run `kici types` to refresh");
+	lines.push("");
+	lines.push("declare module '@kici-dev/sdk' {");
+	const keySourceMap = buildKeySourceMap(environments);
+	lines.push("  interface KnownSecretKeys {");
+	for (const [key, sources] of keySourceMap) {
+		lines.push(`    /** From environment: ${sources.join(", ")} */`);
+		lines.push(`    ${formatProperty(key)}: string;`);
+	}
+	lines.push("  }");
+	lines.push("");
+	lines.push("  interface EnvironmentSecrets {");
+	for (const env of environments) if (env.keys.length === 0) lines.push(`    ${formatProperty(env.name)}: never;`);
+	else {
+		const keyUnion = env.keys.map((k) => `'${escapeQuotes(k)}'`).join(" | ");
+		lines.push(`    ${formatProperty(env.name)}: ${keyUnion};`);
+	}
+	lines.push("  }");
+	lines.push("}");
+	lines.push("");
+	return lines.join("\n");
+}
+//#endregion
+export { generateSecretsDts };
+
+//# sourceMappingURL=secrets-dts.js.map

package/dist/hooks/detector.d.ts

@@ -0,0 +1,39 @@
+/** Supported pre-commit hook tools */
+export type HookToolName = 'husky' | 'lefthook' | 'pre-commit' | 'prek' | 'git';
+/** Detected hook tool with metadata */
+export interface HookTool {
+    readonly name: HookToolName;
+    readonly configPath: string;
+    readonly priority: number;
+}
+/**
+ * Detect which pre-commit tools are configured in the project.
+ *
+ * @param cwd - Directory to check (defaults to process.cwd())
+ * @returns Array of detected tools, sorted by priority (highest first)
+ */
+export declare function detectHookTools(cwd?: string): Promise<HookTool[]>;
+/**
+ * Check if running in a git repository.
+ *
+ * Handles both normal .git directories and .git files used by worktrees
+ * and submodules. For .git files, resolves the "gitdir:" pointer to the
+ * actual git directory.
+ *
+ * @param cwd - Directory to check (defaults to process.cwd())
+ * @returns Path to git directory if found, null otherwise
+ */
+export declare function findGitDir(cwd?: string): Promise<string | null>;
+/**
+ * Get git root directory (the directory containing .git/ or .git file).
+ *
+ * Unlike findGitDir which returns the resolved git directory path,
+ * this returns the working tree root — the directory where .git lives.
+ * For worktrees and submodules, this is the directory containing the
+ * .git file, not the parent of the resolved gitdir path.
+ *
+ * @param cwd - Directory to start from (defaults to process.cwd())
+ * @returns Path to git root, or cwd if not in a git repo
+ */
+export declare function findGitRoot(cwd?: string): Promise<string>;
+//# sourceMappingURL=detector.d.ts.map

package/dist/hooks/detector.js

@@ -0,0 +1,133 @@
+import "../chunk-gOLHoazu.js";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+//#region src/hooks/detector.ts
+const TOOL_CONFIGS = [
+	{
+		name: "husky",
+		configFiles: [".husky/"],
+		priority: 1
+	},
+	{
+		name: "lefthook",
+		configFiles: [
+			"lefthook.yml",
+			".lefthook.yml",
+			".config/lefthook.yml"
+		],
+		priority: 2
+	},
+	{
+		name: "pre-commit",
+		configFiles: [".pre-commit-config.yaml"],
+		priority: 3
+	},
+	{
+		name: "prek",
+		configFiles: ["prek.toml", ".prek.toml"],
+		priority: 4
+	}
+];
+/**
+* Detect which pre-commit tools are configured in the project.
+*
+* @param cwd - Directory to check (defaults to process.cwd())
+* @returns Array of detected tools, sorted by priority (highest first)
+*/
+async function detectHookTools(cwd) {
+	const baseDir = cwd ?? process.cwd();
+	const detected = [];
+	for (const tool of TOOL_CONFIGS) for (const configFile of tool.configFiles) {
+		const configPath = path.join(baseDir, configFile);
+		try {
+			const stats = await stat(configPath);
+			if (stats.isDirectory() || stats.isFile()) {
+				detected.push({
+					name: tool.name,
+					configPath,
+					priority: tool.priority
+				});
+				break;
+			}
+		} catch {}
+	}
+	return detected.sort((a, b) => a.priority - b.priority);
+}
+/**
+* Resolve a .git file (used by worktrees and submodules) to the actual git directory.
+*
+* Git worktrees and submodules use a .git file containing "gitdir: <path>"
+* instead of a .git directory. The path may be absolute or relative to the
+* directory containing the .git file.
+*
+* @param gitFilePath - Path to the .git file
+* @returns Resolved absolute path to the git directory, or null if invalid
+*/
+async function resolveGitFile(gitFilePath) {
+	try {
+		const content = (await readFile(gitFilePath, "utf-8")).trim();
+		if (!content.startsWith("gitdir:")) return null;
+		const gitdir = content.slice(7).trim();
+		if (!gitdir) return null;
+		const resolved = path.resolve(path.dirname(gitFilePath), gitdir);
+		if ((await stat(resolved)).isDirectory()) return resolved;
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Check if running in a git repository.
+*
+* Handles both normal .git directories and .git files used by worktrees
+* and submodules. For .git files, resolves the "gitdir:" pointer to the
+* actual git directory.
+*
+* @param cwd - Directory to check (defaults to process.cwd())
+* @returns Path to git directory if found, null otherwise
+*/
+async function findGitDir(cwd) {
+	let currentPath = path.resolve(cwd ?? process.cwd());
+	while (true) {
+		const gitPath = path.join(currentPath, ".git");
+		try {
+			const stats = await stat(gitPath);
+			if (stats.isDirectory()) return gitPath;
+			if (stats.isFile()) {
+				const resolved = await resolveGitFile(gitPath);
+				if (resolved) return resolved;
+			}
+		} catch {}
+		const parentPath = path.dirname(currentPath);
+		if (parentPath === currentPath) return null;
+		currentPath = parentPath;
+	}
+}
+/**
+* Get git root directory (the directory containing .git/ or .git file).
+*
+* Unlike findGitDir which returns the resolved git directory path,
+* this returns the working tree root — the directory where .git lives.
+* For worktrees and submodules, this is the directory containing the
+* .git file, not the parent of the resolved gitdir path.
+*
+* @param cwd - Directory to start from (defaults to process.cwd())
+* @returns Path to git root, or cwd if not in a git repo
+*/
+async function findGitRoot(cwd) {
+	let currentPath = path.resolve(cwd ?? process.cwd());
+	while (true) {
+		const gitPath = path.join(currentPath, ".git");
+		try {
+			const stats = await stat(gitPath);
+			if (stats.isDirectory() || stats.isFile()) return currentPath;
+		} catch {}
+		const parentPath = path.dirname(currentPath);
+		if (parentPath === currentPath) return cwd ?? process.cwd();
+		currentPath = parentPath;
+	}
+}
+//#endregion
+export { detectHookTools, findGitDir, findGitRoot };
+
+//# sourceMappingURL=detector.js.map

package/dist/hooks/index.d.ts

@@ -0,0 +1,6 @@
+export { detectHookTools, findGitDir, findGitRoot } from './detector.js';
+export type { HookTool, HookToolName } from './detector.js';
+export { getHookTemplate, hasKiciHook, KICI_HOOK_MARKER } from './templates.js';
+export { installHook } from './installer.js';
+export type { InstallResult, InstallOptions } from './installer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.js

@@ -0,0 +1,5 @@
+import "../chunk-gOLHoazu.js";
+import { detectHookTools, findGitDir, findGitRoot } from "./detector.js";
+import { KICI_HOOK_MARKER, getHookTemplate, hasKiciHook } from "./templates.js";
+import { installHook } from "./installer.js";
+export { KICI_HOOK_MARKER, detectHookTools, findGitDir, findGitRoot, getHookTemplate, hasKiciHook, installHook };

package/dist/hooks/installer.d.ts

@@ -0,0 +1,24 @@
+import type { HookToolName } from './detector.js';
+/** Result of hook installation */
+export interface InstallResult {
+    readonly success: boolean;
+    readonly tool: HookToolName;
+    readonly path: string;
+    readonly action: 'created' | 'updated' | 'skipped';
+    readonly message: string;
+}
+/** Options for hook installation */
+export interface InstallOptions {
+    /** Working directory (defaults to process.cwd()) */
+    cwd?: string;
+    /** Use @kici-dev/compiler from local Verdaccio instead of the public kici package */
+    useVerdaccio?: boolean;
+}
+/**
+ * Install kici compile hook using the specified tool.
+ *
+ * Uses each tool's native CLI for initialization and git-hook wiring,
+ * falling back to manual file creation only when the CLI is unavailable.
+ */
+export declare function installHook(tool: HookToolName, options?: InstallOptions): Promise<InstallResult>;
+//# sourceMappingURL=installer.d.ts.map

package/dist/hooks/installer.js

@@ -0,0 +1,328 @@
+import "../chunk-gOLHoazu.js";
+import { findGitDir } from "./detector.js";
+import { getHookTemplate, hasKiciHook } from "./templates.js";
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+//#region src/hooks/installer.ts
+const execAsync = promisify(exec);
+/** Run a shell command in a directory. Returns stdout on success. */
+async function runCommand(cmd, cwd) {
+	const { stdout } = await execAsync(cmd, {
+		cwd,
+		timeout: 3e4
+	});
+	return stdout.trim();
+}
+/** Check if a directory exists */
+async function dirExists(dirPath) {
+	try {
+		return (await stat(dirPath)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/**
+* Install kici compile hook using the specified tool.
+*
+* Uses each tool's native CLI for initialization and git-hook wiring,
+* falling back to manual file creation only when the CLI is unavailable.
+*/
+async function installHook(tool, options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	const command = `${options.useVerdaccio ? "npx -y @kici-dev/compiler@latest" : "npx -y kici@latest"} compile && git add .kici/kici.lock.json`;
+	switch (tool) {
+		case "husky": return installHuskyHook(cwd, command);
+		case "lefthook": return installLefthookHook(cwd, command);
+		case "pre-commit":
+		case "prek": return installPreCommitHook(cwd, command, tool);
+		case "git": return installGitHook(cwd, command);
+		default: return {
+			success: false,
+			tool,
+			path: "",
+			action: "skipped",
+			message: `Unknown hook tool: ${tool}`
+		};
+	}
+}
+/**
+* Install hook for Husky.
+*
+* When .husky/ doesn't exist, runs `npx husky init` to properly initialize
+* (sets core.hooksPath, creates directory structure). Falls back to manual
+* setup if the CLI is unavailable.
+*
+* Then creates or appends our command to .husky/pre-commit.
+*/
+async function installHuskyHook(cwd, command) {
+	const hookDir = path.join(cwd, ".husky");
+	const hookPath = path.join(hookDir, "pre-commit");
+	const template = getHookTemplate("husky");
+	try {
+		const huskyReady = await dirExists(hookDir);
+		let freshInit = false;
+		if (!huskyReady) freshInit = await initHusky(cwd, hookDir);
+		let content = "";
+		let action = "created";
+		try {
+			content = await readFile(hookPath, "utf-8");
+			if (hasKiciHook(content)) return {
+				success: true,
+				tool: "husky",
+				path: hookPath,
+				action: "skipped",
+				message: "kici hook already installed"
+			};
+			if (freshInit) {
+				content = template.getFullScript(command);
+				action = "created";
+			} else {
+				content += template.getCommand(command);
+				action = "updated";
+			}
+		} catch {
+			content = template.getFullScript(command);
+		}
+		await writeFile(hookPath, content, "utf-8");
+		try {
+			await chmod(hookPath, 493);
+		} catch {}
+		return {
+			success: true,
+			tool: "husky",
+			path: hookPath,
+			action,
+			message: action === "created" ? "Created .husky/pre-commit with kici compile" : "Added kici compile to .husky/pre-commit"
+		};
+	} catch (err) {
+		return {
+			success: false,
+			tool: "husky",
+			path: hookPath,
+			action: "skipped",
+			message: `Failed to install husky hook: ${err.message}`
+		};
+	}
+}
+/**
+* Initialize husky using its CLI, with manual fallback.
+* Returns true if this was a fresh initialization.
+*/
+async function initHusky(cwd, hookDir) {
+	try {
+		await runCommand("npx --yes husky init", cwd);
+		return true;
+	} catch {
+		await mkdir(hookDir, { recursive: true });
+		try {
+			await runCommand("git config core.hooksPath .husky", cwd);
+		} catch {}
+		return true;
+	}
+}
+/**
+* Install hook for Lefthook.
+*
+* Edits lefthook.yml to add the kici-compile command, then runs
+* `npx lefthook install` to wire up git hooks.
+*/
+async function installLefthookHook(cwd, command) {
+	const configFiles = [
+		"lefthook.yml",
+		".lefthook.yml",
+		".config/lefthook.yml"
+	];
+	let configPath = "";
+	let content = "";
+	for (const file of configFiles) {
+		const filePath = path.join(cwd, file);
+		try {
+			content = await readFile(filePath, "utf-8");
+			configPath = filePath;
+			break;
+		} catch {}
+	}
+	if (!configPath) {
+		configPath = path.join(cwd, "lefthook.yml");
+		content = `# Lefthook configuration
+# https://lefthook.dev/configuration/
+
+pre-commit:
+  parallel: true
+  commands:
+`;
+	}
+	if (hasKiciHook(content)) return {
+		success: true,
+		tool: "lefthook",
+		path: configPath,
+		action: "skipped",
+		message: "kici hook already installed"
+	};
+	const hookConfig = getHookTemplate("lefthook").getCommand(command);
+	if (content.includes("pre-commit:")) {
+		const preCommitIdx = content.indexOf("pre-commit:");
+		const restAfterKey = content.slice(preCommitIdx + 11);
+		const sectionEnd = restAfterKey.match(/\n[a-zA-Z]/)?.index ?? restAfterKey.length;
+		if (restAfterKey.slice(0, sectionEnd).includes("commands:")) content = content.replace(/(pre-commit:[\s\S]*?commands:)/, `$1\n${hookConfig}`);
+		else content = content.replace(/(pre-commit:.*)/, `$1\n  commands:\n${hookConfig}`);
+	} else content += `\npre-commit:\n  parallel: true\n  commands:\n${hookConfig}\n`;
+	try {
+		await writeFile(configPath, content, "utf-8");
+		try {
+			await runCommand("npx lefthook install", cwd);
+		} catch {}
+		return {
+			success: true,
+			tool: "lefthook",
+			path: configPath,
+			action: "updated",
+			message: "Added kici-compile command to lefthook.yml"
+		};
+	} catch (err) {
+		return {
+			success: false,
+			tool: "lefthook",
+			path: configPath,
+			action: "skipped",
+			message: `Failed to update lefthook config: ${err.message}`
+		};
+	}
+}
+/**
+* Install hook for pre-commit or prek.
+*
+* Both use .pre-commit-config.yaml format.
+* After editing the config, runs `pre-commit install` to wire up git hooks.
+*/
+async function installPreCommitHook(cwd, command, tool) {
+	const configPath = path.join(cwd, ".pre-commit-config.yaml");
+	let content = "";
+	try {
+		content = await readFile(configPath, "utf-8");
+	} catch {
+		content = `# pre-commit configuration
+# https://pre-commit.com/
+
+repos:
+`;
+	}
+	if (hasKiciHook(content)) return {
+		success: true,
+		tool,
+		path: configPath,
+		action: "skipped",
+		message: "kici hook already installed"
+	};
+	const hookConfig = getHookTemplate(tool).getCommand(command);
+	if (content.includes("repos:")) content = content.replace(/(repos:)/, `$1\n${hookConfig}`);
+	else content += `repos:\n${hookConfig}\n`;
+	try {
+		await writeFile(configPath, content, "utf-8");
+		const installCmd = tool === "prek" ? "prek install" : "pre-commit install";
+		try {
+			await runCommand(installCmd, cwd);
+		} catch {}
+		return {
+			success: true,
+			tool,
+			path: configPath,
+			action: "updated",
+			message: `Added kici hook to .pre-commit-config.yaml`
+		};
+	} catch (err) {
+		return {
+			success: false,
+			tool,
+			path: configPath,
+			action: "skipped",
+			message: `Failed to update pre-commit config: ${err.message}`
+		};
+	}
+}
+/**
+* Resolve the common git directory for hook installation.
+*
+* Git worktrees have a `commondir` file pointing to the shared git directory.
+* Hooks must be installed in the common directory (e.g., `.git/hooks/`) rather
+* than the worktree-specific directory (e.g., `.git/worktrees/<name>/hooks/`),
+* because git only looks for hooks in the common hooks directory.
+*/
+async function resolveCommonGitDir(gitDir) {
+	try {
+		const commondir = (await readFile(path.join(gitDir, "commondir"), "utf-8")).trim();
+		return path.resolve(gitDir, commondir);
+	} catch {
+		return gitDir;
+	}
+}
+/**
+* Install raw git hook.
+* Creates or appends to .git/hooks/pre-commit.
+* Handles worktrees by resolving the common git directory for hooks.
+*/
+async function installGitHook(cwd, command) {
+	const gitDir = await findGitDir(cwd);
+	if (!gitDir) return {
+		success: false,
+		tool: "git",
+		path: "",
+		action: "skipped",
+		message: "Not in a git repository"
+	};
+	const commonGitDir = await resolveCommonGitDir(gitDir);
+	const hookDir = path.join(commonGitDir, "hooks");
+	const hookPath = path.join(hookDir, "pre-commit");
+	const template = getHookTemplate("git");
+	try {
+		await mkdir(hookDir, { recursive: true });
+		let content = "";
+		let action = "created";
+		try {
+			content = await readFile(hookPath, "utf-8");
+			action = "updated";
+			if (hasKiciHook(content)) return {
+				success: true,
+				tool: "git",
+				path: hookPath,
+				action: "skipped",
+				message: "kici hook already installed"
+			};
+		} catch {
+			content = template.getFullScript(command);
+			await writeFile(hookPath, content, "utf-8");
+			await chmod(hookPath, 493);
+			return {
+				success: true,
+				tool: "git",
+				path: hookPath,
+				action: "created",
+				message: "Created .git/hooks/pre-commit with kici compile"
+			};
+		}
+		content += template.getCommand(command);
+		await writeFile(hookPath, content, "utf-8");
+		await chmod(hookPath, 493);
+		return {
+			success: true,
+			tool: "git",
+			path: hookPath,
+			action,
+			message: "Added kici compile to .git/hooks/pre-commit"
+		};
+	} catch (err) {
+		return {
+			success: false,
+			tool: "git",
+			path: hookPath,
+			action: "skipped",
+			message: `Failed to install git hook: ${err.message}`
+		};
+	}
+}
+//#endregion
+export { installHook };
+
+//# sourceMappingURL=installer.js.map

package/dist/hooks/templates.d.ts

@@ -0,0 +1,26 @@
+import type { HookToolName } from './detector.js';
+/** Marker comment to identify kici-added hooks */
+export declare const KICI_HOOK_MARKER = "# KiCI: compile workflows on commit";
+/** Template configuration for each hook tool */
+interface HookTemplate {
+    /** Get shell command/config to add */
+    getCommand: (command: string) => string;
+    /** Full hook script template (for new hooks) */
+    getFullScript?: (command: string) => string;
+}
+/**
+ * Get the hook template for a specific tool.
+ *
+ * @param tool - Hook tool name
+ * @returns Template configuration for the tool
+ */
+export declare function getHookTemplate(tool: HookToolName): HookTemplate;
+/**
+ * Check if a file already contains the kici hook.
+ *
+ * @param content - File content to check
+ * @returns true if kici hook marker is present
+ */
+export declare function hasKiciHook(content: string): boolean;
+export {};
+//# sourceMappingURL=templates.d.ts.map