@gajae-code/coding-agent 0.18.11 → 0.19.0

package/src/migrate/executor.ts

@@ -9,6 +9,7 @@
 import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { getTrustedHomeDir } from "@gajae-code/utils";
 import { upsertMCPServer } from "../runtime-mcp/config-writer";
 import type { MigrateAction } from "./types";
 
@@ -19,17 +20,23 @@ function trustedSkillDestinationBase(destination: string): string {
 	return path.basename(scopeRoot) === ".gjc" ? path.dirname(scopeRoot) : scopeRoot;
 }
 
-async function ensureRealDirectoryPathNoFollow(directory: string, trustedBase: string): Promise<void> {
+async function ensureRealDirectoryPathNoFollow(
+	directory: string,
+	trustedBase: string,
+	label = "skill destination",
+	createMissing = true,
+	mode?: number,
+): Promise<void> {
 	const resolvedBase = path.resolve(trustedBase);
 	const resolvedDirectory = path.resolve(directory);
 	const relative = path.relative(resolvedBase, resolvedDirectory);
 	if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-		throw new Error(`skill destination escapes trusted base: ${resolvedDirectory}`);
+		throw new Error(`${label} escapes trusted base: ${resolvedDirectory}`);
 	}
 
 	const baseStat = await fs.stat(resolvedBase);
 	if (!baseStat.isDirectory()) {
-		throw new Error(`skill destination base is not a directory: ${resolvedBase}`);
+		throw new Error(`${label} base is not a directory: ${resolvedBase}`);
 	}
 
 	let current = resolvedBase;
@@ -38,14 +45,17 @@ async function ensureRealDirectoryPathNoFollow(directory: string, trustedBase: s
 		try {
 			const stat = await fs.lstat(current);
 			if (!stat.isDirectory() || stat.isSymbolicLink()) {
-				throw new Error(`skill destination ancestor is not a real directory: ${current}`);
+				throw new Error(`${label} ancestor is not a real directory: ${current}`);
 			}
 		} catch (error) {
 			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-			await fs.mkdir(current);
+			// A missing project `.gjc` is created by the MCP writer (mode 0o700).
+			// Do not mkdir here, or that mode is lost. An existing symlink still fails above.
+			if (!createMissing) return;
+			await fs.mkdir(current, mode === undefined ? undefined : { mode });
 			const stat = await fs.lstat(current);
 			if (!stat.isDirectory() || stat.isSymbolicLink()) {
-				throw new Error(`skill destination ancestor is not a real directory: ${current}`);
+				throw new Error(`${label} ancestor is not a real directory: ${current}`);
 			}
 		}
 	}
@@ -66,7 +76,161 @@ async function writeSkillFileNoFollow(destination: string, content: string): Pro
 	}
 }
 
-export async function executeActions(actions: MigrateAction[]): Promise<MigrateAction[]> {
+async function ensureInstructionDirectory(
+	directory: string,
+	project: boolean,
+	label = "instruction destination",
+): Promise<void> {
+	let trustedBase = path.dirname(directory);
+	if (!project) {
+		const home = path.resolve(getTrustedHomeDir());
+		const resolvedDirectory = path.resolve(directory);
+		const relative = path.relative(home, resolvedDirectory);
+		const isWithinHome =
+			relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+		if (isWithinHome) {
+			trustedBase = home;
+		} else {
+			let current = path.dirname(resolvedDirectory);
+			while (true) {
+				try {
+					const stat = await fs.lstat(current);
+					if (!stat.isDirectory() || stat.isSymbolicLink()) {
+						throw new Error(`user ${label} ancestor is not a real directory: ${current}`);
+					}
+					trustedBase = current;
+					break;
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+					const parent = path.dirname(current);
+					if (parent === current) throw error;
+					current = parent;
+				}
+			}
+		}
+	}
+	await ensureRealDirectoryPathNoFollow(directory, trustedBase, label, true, 0o700);
+}
+
+async function writeInstructionFileNoFollow(destination: string, content: string, project: boolean): Promise<void> {
+	await ensureInstructionDirectory(path.dirname(destination), project);
+	const handle = await fs.open(
+		destination,
+		fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_TRUNC | fsSync.constants.O_NOFOLLOW,
+		0o666,
+	);
+	try {
+		await handle.writeFile(content, "utf-8");
+	} finally {
+		await handle.close();
+	}
+}
+
+async function writeAgentFileNoFollow(
+	destination: string,
+	content: string,
+	project: boolean,
+	createOnly: boolean,
+): Promise<void> {
+	const destinationDirectory = path.dirname(destination);
+	if (project) {
+		const agentsRoot = path.dirname(destinationDirectory);
+		const agentRoot = path.dirname(agentsRoot);
+		await ensureRealDirectoryPathNoFollow(agentRoot, path.dirname(agentRoot), "agent destination", true, 0o700);
+		await ensureRealDirectoryPathNoFollow(agentsRoot, agentRoot, "agent destination", true, 0o700);
+		await ensureRealDirectoryPathNoFollow(destinationDirectory, agentsRoot, "agent destination", true, 0o700);
+	} else {
+		await ensureInstructionDirectory(destinationDirectory, false, "agent destination");
+	}
+	const handle = await fs.open(
+		destination,
+		createOnly
+			? fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL | fsSync.constants.O_NOFOLLOW
+			: fsSync.constants.O_WRONLY |
+					fsSync.constants.O_CREAT |
+					fsSync.constants.O_TRUNC |
+					fsSync.constants.O_NOFOLLOW,
+		0o666,
+	);
+	try {
+		await handle.writeFile(content, "utf-8");
+	} finally {
+		await handle.close();
+	}
+}
+
+/** Generated hook modules live beside the agent's own hooks, so they use the same no-follow rules. */
+async function writeHookModuleNoFollow(destination: string, content: string, createOnly: boolean): Promise<void> {
+	await ensureInstructionDirectory(path.dirname(destination), false, "hook destination");
+	const handle = await fs.open(
+		destination,
+		createOnly
+			? fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL | fsSync.constants.O_NOFOLLOW
+			: fsSync.constants.O_WRONLY |
+					fsSync.constants.O_CREAT |
+					fsSync.constants.O_TRUNC |
+					fsSync.constants.O_NOFOLLOW,
+		0o666,
+	);
+	try {
+		await handle.writeFile(content, "utf-8");
+	} finally {
+		await handle.close();
+	}
+}
+
+async function writeCommandFileNoFollow(
+	destination: string,
+	content: string,
+	name: string,
+	project: boolean,
+	createOnly: boolean,
+): Promise<void> {
+	const destinationDirectory = path.dirname(destination);
+	if (project) {
+		const nameParts = name.split(":");
+		let commandsRoot = destinationDirectory;
+		for (let index = 1; index < nameParts.length; index++) commandsRoot = path.dirname(commandsRoot);
+		const agentRoot = path.dirname(commandsRoot);
+		await ensureRealDirectoryPathNoFollow(
+			agentRoot,
+			path.dirname(agentRoot),
+			"slash command destination",
+			true,
+			0o700,
+		);
+		await ensureRealDirectoryPathNoFollow(commandsRoot, agentRoot, "slash command destination", true, 0o700);
+		await ensureRealDirectoryPathNoFollow(
+			destinationDirectory,
+			commandsRoot,
+			"slash command destination",
+			true,
+			0o700,
+		);
+	} else {
+		await ensureInstructionDirectory(destinationDirectory, false, "slash command destination");
+	}
+
+	const handle = await fs.open(
+		destination,
+		fsSync.constants.O_WRONLY |
+			fsSync.constants.O_CREAT |
+			fsSync.constants.O_TRUNC |
+			fsSync.constants.O_NOFOLLOW |
+			(createOnly ? fsSync.constants.O_EXCL : 0),
+		0o666,
+	);
+	try {
+		await handle.writeFile(content, "utf-8");
+	} finally {
+		await handle.close();
+	}
+}
+
+export async function executeActions(
+	actions: MigrateAction[],
+	options?: { project?: boolean },
+): Promise<MigrateAction[]> {
 	const out: MigrateAction[] = [];
 	for (const action of actions) {
 		if (action.operation !== "create" && action.operation !== "update") {
@@ -75,6 +239,17 @@ export async function executeActions(actions: MigrateAction[]): Promise<MigrateA
 		}
 		try {
 			if (action.type === "mcp" && action.mcp && action.name && action.destination) {
+				// `project` is the migrate scope, not a guess from the directory name.
+				// A user agent dir may itself be named `.gjc`.
+				if (options?.project) {
+					const directory = path.dirname(action.destination);
+					await ensureRealDirectoryPathNoFollow(
+						directory,
+						path.dirname(path.resolve(directory)),
+						"mcp destination",
+						false,
+					);
+				}
 				await upsertMCPServer(action.destination, action.name, action.mcp.config, {
 					force: action.operation === "update",
 				});
@@ -82,10 +257,50 @@ export async function executeActions(actions: MigrateAction[]): Promise<MigrateA
 			} else if (action.type === "skill" && action.skill && action.destination) {
 				await writeSkillFileNoFollow(action.destination, action.skill.content);
 				out.push(action);
+			} else if (action.type === "instruction" && action.instruction && action.destination) {
+				await writeInstructionFileNoFollow(
+					action.destination,
+					action.instruction.content,
+					options?.project ?? false,
+				);
+				out.push(action);
+			} else if (action.type === "hook" && action.hook && action.destination) {
+				await writeHookModuleNoFollow(action.destination, action.hook.content, action.operation === "create");
+				out.push(action);
+			} else if (action.type === "agent" && action.agent && action.destination) {
+				await writeAgentFileNoFollow(
+					action.destination,
+					action.agent.content,
+					options?.project ?? false,
+					action.operation === "create",
+				);
+				out.push(action);
+			} else if (action.type === "command" && action.command && action.destination && action.name) {
+				await writeCommandFileNoFollow(
+					action.destination,
+					action.command.content,
+					action.name,
+					options?.project ?? false,
+					action.operation === "create",
+				);
+				out.push(action);
 			} else {
 				out.push(action);
 			}
 		} catch (error) {
+			if (
+				(action.type === "command" || action.type === "agent") &&
+				action.operation === "create" &&
+				(error as NodeJS.ErrnoException).code === "EEXIST"
+			) {
+				out.push({
+					...action,
+					operation: "skip",
+					status: "skipped_exists",
+					reason: "destination appeared after planning; refusing to overwrite it",
+				});
+				continue;
+			}
 			out.push({
 				...action,
 				operation: "fail",

package/src/migrate/hook-module.ts

@@ -0,0 +1,193 @@
+/**
+ * Render a gjc hook module from imported foreign hook commands.
+ *
+ * Claude Code hooks are shell commands: the runtime writes a JSON payload to
+ * stdin and reads the exit code. `PreToolUse` blocks on exit 2 with stderr as the
+ * reason; every other event is observational. gjc hooks are TypeScript modules
+ * that subscribe to events in-process, so the importer reproduces the foreign
+ * contract rather than rewriting the commands.
+ *
+ * Only events whose semantics are unambiguous are translated. The payload keeps
+ * the foreign field names so an existing script that reads its JSON keeps working;
+ * fields this host cannot supply are omitted instead of guessed, which the module
+ * header states.
+ */
+import type { HookCandidate, MigrateSource } from "./types";
+
+/** Foreign event -> gjc hook event. Blocking events are marked separately. */
+const EVENT_MAP: Record<string, { event: string; blocking: boolean }> = {
+	PreToolUse: { event: "tool_call", blocking: true },
+	PostToolUse: { event: "tool_result", blocking: false },
+	SessionStart: { event: "session_start", blocking: false },
+	Stop: { event: "turn_end", blocking: false },
+};
+
+export function isSupportedHookEvent(event: string): boolean {
+	return event in EVENT_MAP;
+}
+
+/** Foreign events this importer translates, for user-facing messages. */
+export const SUPPORTED_HOOK_EVENTS: readonly string[] = Object.keys(EVENT_MAP);
+
+interface RenderedHook {
+	event: string;
+	blocking: boolean;
+	matcher?: string;
+	command: string;
+	sourceEvent: string;
+}
+
+function constantName(event: string): string {
+	return event.replace(/[^a-z_]/g, "_").toUpperCase();
+}
+
+function renderHookLiteral(hook: RenderedHook): string {
+	const parts = [`event: ${JSON.stringify(hook.sourceEvent)}`, `command: ${JSON.stringify(hook.command)}`];
+	if (hook.matcher) parts.push(`matcher: ${JSON.stringify(hook.matcher)}`);
+	return `\t{ ${parts.join(", ")} },`;
+}
+
+/**
+ * Build the module source. The result is deterministic for a given candidate
+ * list, so a dry-run report and a live write describe the same file.
+ */
+export function renderHookModule(source: MigrateSource, candidates: readonly HookCandidate[]): string {
+	const hooks: RenderedHook[] = [];
+	for (const candidate of candidates) {
+		const mapped = EVENT_MAP[candidate.event];
+		if (!mapped) continue;
+		hooks.push({
+			event: mapped.event,
+			blocking: mapped.blocking,
+			matcher: candidate.matcher,
+			command: candidate.command,
+			sourceEvent: candidate.event,
+		});
+	}
+	const byEvent = new Map<string, RenderedHook[]>();
+	for (const hook of hooks) {
+		const list = byEvent.get(hook.event) ?? [];
+		list.push(hook);
+		byEvent.set(hook.event, list);
+	}
+	const eventNames = [...byEvent.keys()].sort();
+	const blocks = eventNames
+		.map(event => {
+			const entries = (byEvent.get(event) ?? []).map(renderHookLiteral).join("\n");
+			return `const ${constantName(event)}_HOOKS: readonly ImportedHook[] = [\n${entries}\n];`;
+		})
+		.join("\n\n");
+	const registrations = eventNames
+		.map(event => {
+			const blocking = byEvent.get(event)?.some(hook => hook.blocking) ?? false;
+			const register = blocking ? "registerBlocking" : "registerObservational";
+			return `\t${register}(api, ${JSON.stringify(event)}, ${constantName(event)}_HOOKS);`;
+		})
+		.join("\n");
+
+	return `/**
+ * Generated by \`gjc migrate --from ${source}\`. Re-run with --force to regenerate.
+ *
+ * These hooks were shell commands in ${source}. Each command receives a JSON
+ * payload on stdin under the origin's field names; fields this runtime cannot
+ * supply (session id, transcript path) are omitted rather than invented.
+ * \`PreToolUse\` blocks the tool when the command exits 2 and uses its stderr as
+ * the reason, which is the origin contract; the other events only run the
+ * command.
+ */
+import { spawn } from "node:child_process";
+
+interface ImportedHook {
+	event: string;
+	command: string;
+	matcher?: string;
+}
+
+interface HookCommandResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+}
+
+interface HookApi {
+	on(event: string, handler: (payload: unknown, context: { cwd?: string }) => unknown): void;
+}
+
+${blocks}
+
+function matches(matcher: string | undefined, toolName: string | undefined): boolean {
+	if (!matcher || !matcher.trim()) return true;
+	if (!toolName) return false;
+	try {
+		return new RegExp(\`^(?:\${matcher})$\`).test(toolName);
+	} catch {
+		return matcher === toolName;
+	}
+}
+
+function shellCommand(command: string): string[] {
+	return process.platform === "win32"
+		? [process.env.ComSpec ?? "cmd.exe", "/d", "/s", "/c", command]
+		: ["/bin/bash", "-lc", command];
+}
+
+async function runHook(hook: ImportedHook, payload: unknown): Promise<HookCommandResult> {
+	const [file, ...args] = shellCommand(hook.command);
+	const child = spawn(file, args, { stdio: ["pipe", "pipe", "pipe"] });
+	child.stdin?.end(JSON.stringify(payload));
+	let stdout = "";
+	let stderr = "";
+	child.stdout?.on("data", chunk => {
+		stdout += String(chunk);
+	});
+	child.stderr?.on("data", chunk => {
+		stderr += String(chunk);
+	});
+	const code = await new Promise<number>(resolve => {
+		child.on("error", () => resolve(1));
+		child.on("close", value => resolve(value ?? 1));
+	});
+	return { code, stdout, stderr };
+}
+
+function registerBlocking(api: HookApi, event: string, hooks: readonly ImportedHook[]): void {
+	api.on(event, async (payload, context) => {
+		const record = payload as { toolName?: string; input?: unknown };
+		for (const hook of hooks) {
+			if (!matches(hook.matcher, record?.toolName)) continue;
+			const result = await runHook(hook, {
+				hook_event_name: hook.event,
+				tool_name: record?.toolName,
+				tool_input: record?.input,
+				cwd: context?.cwd,
+			});
+			if (result.code === 2) {
+				return { block: true, reason: result.stderr.trim() || \`blocked by imported \${hook.event} hook\` };
+			}
+		}
+		return undefined;
+	});
+}
+
+function registerObservational(api: HookApi, event: string, hooks: readonly ImportedHook[]): void {
+	api.on(event, async (payload, context) => {
+		const record = payload as { toolName?: string; input?: unknown; turnIndex?: number };
+		for (const hook of hooks) {
+			if (event === "tool_result" && !matches(hook.matcher, record?.toolName)) continue;
+			await runHook(hook, {
+				hook_event_name: hook.event,
+				tool_name: record?.toolName,
+				tool_input: record?.input,
+				turn_index: record?.turnIndex,
+				cwd: context?.cwd,
+			});
+		}
+		return undefined;
+	});
+}
+
+export default (api: HookApi): void => {
+${registrations}
+};
+`;
+}

package/src/migrate/report.ts

@@ -7,6 +7,7 @@
 import {
 	emptyStatusCounts,
 	isFailureStatus,
+	type ManualAction,
 	type MigrateAction,
 	type MigrateDestinations,
 	type MigrateReport,
@@ -20,6 +21,7 @@ export interface BuildReportInput {
 	warnings: MigrateWarning[];
 	sources: MigrateSource[];
 	destinations: MigrateDestinations;
+	manualActions: ManualAction[];
 	dryRun: boolean;
 	project: boolean;
 	force: boolean;
@@ -27,7 +29,15 @@ export interface BuildReportInput {
 
 export function buildReport(input: BuildReportInput): MigrateReport {
 	const total = emptyStatusCounts();
-	const byType = { mcp: emptyStatusCounts(), skill: emptyStatusCounts(), source: emptyStatusCounts() };
+	const byType = {
+		mcp: emptyStatusCounts(),
+		skill: emptyStatusCounts(),
+		command: emptyStatusCounts(),
+		agent: emptyStatusCounts(),
+		hook: emptyStatusCounts(),
+		instruction: emptyStatusCounts(),
+		source: emptyStatusCounts(),
+	};
 	const bySource = {} as Record<MigrateSource, StatusCounts>;
 	for (const source of input.sources) bySource[source] = emptyStatusCounts();
 
@@ -47,6 +57,7 @@ export function buildReport(input: BuildReportInput): MigrateReport {
 		sources: input.sources,
 		destinations: input.destinations,
 		summary: { total, byType, bySource },
+		manualActions: input.manualActions,
 		actions: input.actions.map(action => ({
 			source: action.source,
 			type: action.type,
@@ -75,10 +86,52 @@ export function renderHuman(report: MigrateReport): string {
 	const mode = report.dryRun ? " (dry-run)" : "";
 	lines.push(`gjc migrate${mode}: ${report.ok ? "ok" : "completed with failures"}`);
 	lines.push(`Sources: ${report.sources.join(", ") || "none"}`);
-	lines.push(`Destination: mcp=${report.destinations.mcpConfigPath} skills=${report.destinations.skillsDir}`);
+	lines.push(
+		`Destination: mcp=${report.destinations.mcpConfigPath} skills=${report.destinations.skillsDir} commands=${report.destinations.commandsDir} agents=${report.destinations.agentsDir} hooks=${report.destinations.hooksDir} instructions=${report.destinations.instructionsPath}`,
+	);
 	lines.push("");
 	lines.push(`MCP:    ${summarizeCounts(report.summary.byType.mcp)}`);
 	lines.push(`Skills: ${summarizeCounts(report.summary.byType.skill)}`);
+	lines.push(`Commands: ${summarizeCounts(report.summary.byType.command)}`);
+	lines.push(`Agents: ${summarizeCounts(report.summary.byType.agent)}`);
+	lines.push(`Hooks:  ${summarizeCounts(report.summary.byType.hook)}`);
+	lines.push(`Instructions: ${summarizeCounts(report.summary.byType.instruction)}`);
+	const commandActions = report.actions.filter(action => action.type === "command");
+	if (commandActions.length > 0) {
+		lines.push("Slash commands:");
+		for (const action of commandActions) {
+			lines.push(
+				`  - [${action.source}] /${action.name ?? ""}: ${action.status}${action.reason ? ` (${action.reason})` : ""}`,
+			);
+		}
+	}
+	const agentActions = report.actions.filter(action => action.type === "agent");
+	if (agentActions.length > 0) {
+		lines.push("Subagents:");
+		for (const action of agentActions) {
+			lines.push(
+				`  - [${action.source}] ${action.name ?? ""}: ${action.status}${action.reason ? ` (${action.reason})` : ""}`,
+			);
+		}
+	}
+	const hookActions = report.actions.filter(action => action.type === "hook");
+	if (hookActions.length > 0) {
+		lines.push("Hooks:");
+		for (const action of hookActions) {
+			lines.push(
+				`  - [${action.source}] ${action.name ?? ""}: ${action.status}${action.reason ? ` (${action.reason})` : ""}`,
+			);
+		}
+	}
+	const instructionActions = report.actions.filter(action => action.type === "instruction");
+	if (instructionActions.length > 0) {
+		lines.push("Instruction files:");
+		for (const action of instructionActions) {
+			lines.push(
+				`  - [${action.source}] ${action.name ?? "AGENTS.md"}: ${action.status}${action.reason ? ` (${action.reason})` : ""}`,
+			);
+		}
+	}
 	if (Object.values(report.summary.byType.source).some(n => n > 0)) {
 		lines.push(`Source: ${summarizeCounts(report.summary.byType.source)}`);
 	}
@@ -92,6 +145,14 @@ export function renderHuman(report: MigrateReport): string {
 		}
 	}
 
+	if (report.manualActions.length > 0) {
+		lines.push("");
+		lines.push("Manual actions:");
+		for (const m of report.manualActions) {
+			lines.push(`  - [${m.source}] ${m.area}: ${m.detail}`);
+		}
+	}
+
 	if (report.warnings.length > 0) {
 		lines.push("");
 		lines.push("Warnings:");