@gajae-code/coding-agent 0.18.12 → 0.19.0

package/src/migrate/adapters/claude-code.ts

@@ -1,19 +1,123 @@
 /**
- * Claude Code adapter: reads `~/.claude.json` (mcpServers), `~/.claude/skills`,
- * and the selected scope's `CLAUDE.md`.
+ * Claude Code adapter: reads MCP servers, user skills, selected-scope commands,
+ * selected-scope subagents, and the selected scope's `CLAUDE.md`.
  */
 import * as path from "node:path";
-import type { AdapterResult, McpCandidate } from "../types";
+import { isSupportedHookEvent, SUPPORTED_HOOK_EVENTS } from "../hook-module";
+import type { AdapterResult, HookCandidate, ManualAction, McpCandidate } from "../types";
 import {
 	type Adapter,
 	type AdapterOptions,
 	collectInstructionFile,
+	collectMarkdownAgents,
+	collectMarkdownCommands,
 	collectSkillDir,
 	parseSourceJson,
+	readOptionalJson,
 	readSourceText,
 } from "./index";
 
 const SOURCE = "claude-code" as const;
+const MAX_LISTED_KEYS = 8;
+
+function listKeys(keys: string[]): string {
+	if (keys.length <= MAX_LISTED_KEYS) return keys.join(", ");
+	return `${keys.slice(0, MAX_LISTED_KEYS).join(", ")}, +${keys.length - MAX_LISTED_KEYS} more`;
+}
+
+function stringArray(value: unknown): string[] {
+	return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+
+/** Flatten a `hooks` object into `{event, matcher?, command}` candidates. */
+function collectHookCommands(hooks: Record<string, unknown>): HookCandidate[] {
+	const candidates: HookCandidate[] = [];
+	for (const [event, matchers] of Object.entries(hooks)) {
+		if (!Array.isArray(matchers)) continue;
+		for (const matcher of matchers) {
+			if (!matcher || typeof matcher !== "object") continue;
+			const record = matcher as Record<string, unknown>;
+			const matcherValue = typeof record.matcher === "string" ? record.matcher.trim() : "";
+			const inner = record.hooks;
+			if (!Array.isArray(inner)) continue;
+			for (const hook of inner) {
+				if (!hook || typeof hook !== "object") continue;
+				const command = (hook as Record<string, unknown>).command;
+				if (typeof command !== "string" || !command.trim()) continue;
+				candidates.push({
+					source: SOURCE,
+					event,
+					...(matcherValue ? { matcher: matcherValue } : {}),
+					command,
+				});
+			}
+		}
+	}
+	return candidates;
+}
+
+/**
+ * Describe Claude Code settings that gjc cannot import. These are reported
+ * rather than translated: gjc hooks are TypeScript modules, model ids are
+ * provider-specific, and an approval policy that changed meaning silently would
+ * be a security regression. Environment values are never read.
+ */
+function describeSettings(data: Record<string, unknown>, label: string): ManualAction[] {
+	const actions: ManualAction[] = [];
+	const hooks = data.hooks;
+	if (hooks && typeof hooks === "object" && !Array.isArray(hooks)) {
+		const byEvent = new Map<string, number>();
+		for (const candidate of collectHookCommands(hooks as Record<string, unknown>)) {
+			if (isSupportedHookEvent(candidate.event)) continue;
+			byEvent.set(candidate.event, (byEvent.get(candidate.event) ?? 0) + 1);
+		}
+		for (const [event, commands] of [...byEvent.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+			actions.push({
+				source: SOURCE,
+				area: `${label}: hooks.${event}`,
+				detail: `${commands} shell command${commands === 1 ? "" : "s"} run on ${event}, which has no faithful gjc equivalent; port ${
+					commands === 1 ? "it" : "them"
+				} by hand to a .gjc/hooks module. Importable events: ${SUPPORTED_HOOK_EVENTS.join(", ")}.`,
+			});
+		}
+	}
+	const model = data.model;
+	if (typeof model === "string" && model.trim()) {
+		actions.push({
+			source: SOURCE,
+			area: `${label}: model`,
+			detail: `model "${model}" is provider-specific and was not imported; select it with gjc config or --model.`,
+		});
+	}
+	const permissions = data.permissions;
+	if (permissions && typeof permissions === "object" && !Array.isArray(permissions)) {
+		const record = permissions as Record<string, unknown>;
+		const allow = stringArray(record.allow).length;
+		const deny = stringArray(record.deny).length;
+		const ask = stringArray(record.ask).length;
+		if (allow + deny + ask > 0) {
+			actions.push({
+				source: SOURCE,
+				area: `${label}: permissions`,
+				detail: `${allow} allow, ${deny} deny, ${ask} ask rule${allow + deny + ask === 1 ? "" : "s"} have no gjc equivalent and were not imported; re-express the approvals you still need in gjc's tool settings.${
+					deny > 0 ? " Deny rules are the security-relevant ones — review them first." : ""
+				}`,
+			});
+		}
+	}
+	const env = data.env;
+	if (env && typeof env === "object" && !Array.isArray(env)) {
+		const keys = Object.keys(env as Record<string, unknown>).sort();
+		if (keys.length > 0) {
+			actions.push({
+				source: SOURCE,
+				area: `${label}: env`,
+				detail: `${keys.length} variable${keys.length === 1 ? "" : "s"} (${listKeys(keys)}) were not imported and their values were not read; export them in your shell or project environment instead.`,
+			});
+		}
+	}
+	return actions;
+}
 
 export const claudeCodeAdapter: Adapter = {
 	source: SOURCE,
@@ -21,8 +125,12 @@ export const claudeCodeAdapter: Adapter = {
 		const result: AdapterResult = {
 			mcpCandidates: [],
 			skillCandidates: [],
+			slashCommandCandidates: [],
+			agentCandidates: [],
+			hookCandidates: [],
 			instructionCandidates: [],
 			diagnostics: [],
+			manualActions: [],
 		};
 
 		const configPath = path.join(homeDir, ".claude.json");
@@ -47,12 +155,42 @@ export const claudeCodeAdapter: Adapter = {
 		result.skillCandidates.push(...skills.candidates);
 		result.diagnostics.push(...skills.diagnostics);
 
+		const commandsDir =
+			scope === "project" ? path.join(cwd, ".claude", "commands") : path.join(homeDir, ".claude", "commands");
+		const commands = await collectMarkdownCommands(commandsDir, SOURCE, { recursive: true });
+		result.slashCommandCandidates.push(...commands.candidates);
+		result.diagnostics.push(...commands.diagnostics);
+
+		const agentsDir =
+			scope === "project" ? path.join(cwd, ".claude", "agents") : path.join(homeDir, ".claude", "agents");
+		const agents = await collectMarkdownAgents(agentsDir, SOURCE);
+		result.agentCandidates.push(...agents.candidates);
+		result.diagnostics.push(...agents.diagnostics);
+
 		const instructionsPath =
 			scope === "project" ? path.join(cwd, "CLAUDE.md") : path.join(homeDir, ".claude", "CLAUDE.md");
 		const instructions = await collectInstructionFile(instructionsPath, SOURCE);
 		result.instructionCandidates.push(...instructions.candidates);
 		result.diagnostics.push(...instructions.diagnostics);
 
+		const settingsFiles =
+			scope === "project"
+				? [path.join(cwd, ".claude", "settings.json"), path.join(cwd, ".claude", "settings.local.json")]
+				: [path.join(homeDir, ".claude", "settings.json")];
+		for (const file of settingsFiles) {
+			const settings = await readOptionalJson(file, SOURCE, "source");
+			if ("absent" in settings) continue;
+			if ("diagnostic" in settings) {
+				result.diagnostics.push(settings.diagnostic);
+				continue;
+			}
+			const settingsHooks = settings.data.hooks;
+			if (settingsHooks && typeof settingsHooks === "object" && !Array.isArray(settingsHooks)) {
+				result.hookCandidates.push(...collectHookCommands(settingsHooks as Record<string, unknown>));
+			}
+			result.manualActions.push(...describeSettings(settings.data, path.basename(file)));
+		}
+
 		return result;
 	},
 };

package/src/migrate/adapters/codex.ts

@@ -1,16 +1,16 @@
 /**
- * Codex adapter: reads `~/.codex/config.toml` ([mcp_servers]), `~/.codex/prompts`,
+ * Codex adapter: reads `~/.codex/config.toml` ([mcp_servers]), user prompts,
  * and user-level `~/.codex/AGENTS.md` instructions. Project AGENTS.md is native GJC input.
  */
 
 import * as path from "node:path";
 import { TOML } from "bun";
-import type { AdapterResult, McpCandidate, SourceDiagnostic } from "../types";
+import type { AdapterResult, ManualAction, McpCandidate, SourceDiagnostic } from "../types";
 import {
 	type Adapter,
 	type AdapterOptions,
 	collectInstructionFile,
-	collectMarkdownPrompts,
+	collectMarkdownCommands,
 	readSourceText,
 } from "./index";
 
@@ -45,14 +45,63 @@ function parseToml(
 	}
 }
 
+/**
+ * Describe `config.toml` settings gjc cannot import. Approvals and sandbox mode
+ * change what the agent may do, so they are reported for the user to re-express
+ * rather than translated. Environment variable names are listed; values are not.
+ */
+function describeCodexSettings(data: Record<string, unknown>): ManualAction[] {
+	const actions: ManualAction[] = [];
+	const model = data.model;
+	if (typeof model === "string" && model.trim()) {
+		actions.push({
+			source: SOURCE,
+			area: "config.toml: model",
+			detail: `model "${model}" is provider-specific and was not imported; select it with gjc config or --model.`,
+		});
+	}
+	for (const key of ["approval_policy", "sandbox_mode"] as const) {
+		const value = data[key];
+		if (typeof value !== "string" || !value.trim()) continue;
+		actions.push({
+			source: SOURCE,
+			area: `config.toml: ${key}`,
+			detail: `"${value}" has no gjc equivalent and was not imported; review gjc's tool approval and sandbox settings.`,
+		});
+	}
+	const policy = data.shell_environment_policy;
+	if (policy && typeof policy === "object" && !Array.isArray(policy)) {
+		const record = policy as Record<string, unknown>;
+		const setKeys = record.set && typeof record.set === "object" ? Object.keys(record.set as object).sort() : [];
+		const unsetKeys = Array.isArray(record.unset)
+			? record.unset.filter((key): key is string => typeof key === "string").sort()
+			: [];
+		if (setKeys.length > 0 || unsetKeys.length > 0) {
+			const parts: string[] = [];
+			if (setKeys.length > 0) parts.push(`sets ${setKeys.join(", ")}`);
+			if (unsetKeys.length > 0) parts.push(`unsets ${unsetKeys.join(", ")}`);
+			actions.push({
+				source: SOURCE,
+				area: "config.toml: shell_environment_policy",
+				detail: `shell_environment_policy ${parts.join(" and ")}; variable names were reported without values and nothing was imported.`,
+			});
+		}
+	}
+	return actions;
+}
+
 export const codexAdapter: Adapter = {
 	source: SOURCE,
 	async collect({ homeDir, scope }: AdapterOptions): Promise<AdapterResult> {
 		const result: AdapterResult = {
 			mcpCandidates: [],
 			skillCandidates: [],
+			slashCommandCandidates: [],
+			agentCandidates: [],
 			instructionCandidates: [],
+			hookCandidates: [],
 			diagnostics: [],
+			manualActions: [],
 		};
 
 		const configPath = path.join(homeDir, ".codex", "config.toml");
@@ -70,11 +119,14 @@ export const codexAdapter: Adapter = {
 						result.mcpCandidates.push({ source: SOURCE, name, raw } satisfies McpCandidate);
 					}
 				}
+				result.manualActions.push(...describeCodexSettings(parsed.data));
 			}
 		}
 
-		const prompts = await collectMarkdownPrompts(path.join(homeDir, ".codex", "prompts"), SOURCE);
-		result.skillCandidates.push(...prompts.candidates);
+		const prompts = await collectMarkdownCommands(path.join(homeDir, ".codex", "prompts"), SOURCE);
+		result.slashCommandCandidates.push(
+			...prompts.candidates.map(candidate => ({ ...candidate, name: `prompts:${candidate.name}` })),
+		);
 		result.diagnostics.push(...prompts.diagnostics);
 
 		if (scope === "user") {

package/src/migrate/adapters/index.ts

@@ -1,15 +1,24 @@
 /**
  * Source adapters for `gjc migrate`.
  *
- * Each adapter returns normalized home-scoped MCP/skill candidates, selected-scope
+ * Each adapter returns normalized MCP/skill/command candidates, selected-scope
  * instruction candidates, and source-level diagnostics. Adapters never connect to
  * anything.
  */
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { isEnoent } from "@gajae-code/utils";
+import { isEnoent, parseFrontmatter } from "@gajae-code/utils";
+import { YAML } from "bun";
 import { normalizeSkill } from "../skill-normalizer";
-import type { AdapterResult, InstructionCandidate, MigrateSource, SkillCandidate, SourceDiagnostic } from "../types";
+import type {
+	AdapterResult,
+	AgentCandidate,
+	InstructionCandidate,
+	MigrateSource,
+	SkillCandidate,
+	SlashCommandCandidate,
+	SourceDiagnostic,
+} from "../types";
 import { claudeCodeAdapter } from "./claude-code";
 import { codexAdapter } from "./codex";
 import { opencodeAdapter } from "./opencode";
@@ -17,9 +26,9 @@ import { opencodeAdapter } from "./opencode";
 export interface AdapterOptions {
 	/** Home directory root; overridable for tests. */
 	homeDir: string;
-	/** Source scope for instructions; other source files remain home-scoped. */
+	/** Source scope for instructions and Claude Code commands. */
 	scope: "project" | "user";
-	/** Project root used when importing project instructions. */
+	/** Project root used when importing project instructions and commands. */
 	cwd: string;
 }
 
@@ -76,6 +85,32 @@ export async function readSourceText(
 	}
 }
 
+/**
+ * Read an optional settings file. A missing file is expected (most setups do not
+ * have every settings file), so unlike `readSourceText` it produces no diagnostic.
+ */
+export async function readOptionalJson(
+	filePath: string,
+	source: MigrateSource,
+	type: SourceDiagnostic["type"],
+): Promise<{ data: Record<string, unknown> } | { diagnostic: SourceDiagnostic } | { absent: true }> {
+	let text: string;
+	try {
+		text = await fs.readFile(filePath, "utf-8");
+	} catch (error) {
+		if (isEnoent(error)) return { absent: true };
+		return {
+			diagnostic: {
+				source,
+				type,
+				status: "failed_io",
+				message: `failed to read ${filePath}: ${(error as Error).message}`,
+			},
+		};
+	}
+	return parseSourceJson(text, filePath, source, type);
+}
+
 /** Parse JSON text, classifying parse errors into a `failed_invalid_source` diagnostic. */
 export function parseSourceJson(
 	text: string,
@@ -214,6 +249,206 @@ export async function collectMarkdownPrompts(
 	return { candidates, diagnostics };
 }
 
+/**
+ * Foreign subagent tools map onto the GJC tool surfaces that carry the same
+ * capability. Anything without an equivalent is dropped from the tool list (and
+ * reported) rather than written into an agent that cannot be loaded.
+ */
+const AGENT_TOOL_EQUIVALENTS: Readonly<Record<string, string | undefined>> = {
+	read: "read",
+	write: "edit",
+	edit: "edit",
+	multiedit: "edit",
+	notebookedit: undefined,
+	bash: "bash",
+	bashoutput: undefined,
+	killbash: undefined,
+	grep: "grep",
+	glob: "glob",
+	ls: undefined,
+	task: "task",
+	agent: "task",
+	webfetch: "web_search",
+	websearch: "web_search",
+	todowrite: undefined,
+	todoread: undefined,
+	exitplanmode: undefined,
+};
+
+/** Bundled agent names an imported agent must never shadow. */
+export const PROTECTED_AGENT_NAMES: ReadonlySet<string> = new Set(["executor", "architect", "planner", "critic"]);
+
+const AGENT_NAME_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function importedAgentTools(raw: unknown, warnings: string[]): string[] | undefined {
+	const list =
+		typeof raw === "string"
+			? raw.split(",")
+			: Array.isArray(raw)
+				? raw.filter((entry): entry is string => typeof entry === "string")
+				: [];
+	const mapped: string[] = [];
+	for (const entry of list) {
+		const key = entry.trim().toLowerCase();
+		if (!key) continue;
+		if (!(key in AGENT_TOOL_EQUIVALENTS)) {
+			warnings.push(`dropped unsupported agent tool "${entry.trim()}"`);
+			continue;
+		}
+		const equivalent = AGENT_TOOL_EQUIVALENTS[key];
+		if (!equivalent) {
+			warnings.push(`dropped agent tool "${entry.trim()}" (no GJC equivalent)`);
+			continue;
+		}
+		if (!mapped.includes(equivalent)) mapped.push(equivalent);
+	}
+	return mapped.length > 0 ? mapped : undefined;
+}
+
+/**
+ * Collect subagents from a flat `<agentsDir>/*.md` directory. Frontmatter is
+ * rewritten so the loaded name matches the destination file name, and tool lists
+ * are translated to GJC tools.
+ */
+export async function collectMarkdownAgents(
+	dir: string,
+	source: MigrateSource,
+): Promise<{ candidates: AgentCandidate[]; diagnostics: SourceDiagnostic[] }> {
+	const candidates: AgentCandidate[] = [];
+	const diagnostics: SourceDiagnostic[] = [];
+	const entries = await fs.readdir(dir, { withFileTypes: true }).catch((error: unknown) => {
+		if (isEnoent(error)) {
+			diagnostics.push({
+				source,
+				type: "agent",
+				status: "skipped_absent_source",
+				message: `no agents dir at ${dir}`,
+			});
+		} else {
+			diagnostics.push({
+				source,
+				type: "agent",
+				status: "failed_io",
+				message: `failed to read ${dir}: ${(error as Error).message}`,
+			});
+		}
+		return undefined;
+	});
+	if (!entries) return { candidates, diagnostics };
+
+	for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+		if (entry.name.startsWith(".")) continue;
+		if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+		const entryPath = path.join(dir, entry.name);
+		const read = await readSourceText(entryPath, source, "agent");
+		if ("diagnostic" in read) {
+			diagnostics.push(read.diagnostic);
+			continue;
+		}
+
+		const warnings: string[] = [];
+		const { frontmatter, body } = parseFrontmatter(read.text, { location: entryPath, level: "off" });
+		const rawName = typeof frontmatter.name === "string" ? frontmatter.name.trim() : entry.name.slice(0, -3);
+		const description = typeof frontmatter.description === "string" ? frontmatter.description.trim() : "";
+		if (!AGENT_NAME_SEGMENT.test(rawName)) {
+			diagnostics.push({
+				source,
+				type: "agent",
+				status: "failed_invalid_source",
+				message: `unsupported agent name "${rawName}" in ${entry.name}; names must use letters, numbers, dots, underscores, or hyphens`,
+			});
+			continue;
+		}
+		if (!description || !body.trim()) {
+			diagnostics.push({
+				source,
+				type: "agent",
+				status: "failed_invalid_source",
+				message: `agent ${entry.name} needs both a description and a prompt body`,
+			});
+			continue;
+		}
+
+		const tools = importedAgentTools(frontmatter.tools, warnings);
+		const normalized: Record<string, unknown> = { name: rawName, description, ...(tools ? { tools } : {}) };
+		const yaml = YAML.stringify(normalized).trimEnd();
+		candidates.push({
+			source,
+			name: rawName,
+			content: `---\n${yaml}\n---\n\n${body.trim()}\n`,
+			warnings,
+		});
+	}
+	return { candidates, diagnostics };
+}
+
+/**
+ * Collect Markdown slash commands. Nested command directories are represented
+ * with colon-separated names, matching Claude Code's `/group:command` syntax.
+ */
+export async function collectMarkdownCommands(
+	dir: string,
+	source: MigrateSource,
+	options: { recursive?: boolean } = {},
+): Promise<{ candidates: SlashCommandCandidate[]; diagnostics: SourceDiagnostic[] }> {
+	const candidates: SlashCommandCandidate[] = [];
+	const diagnostics: SourceDiagnostic[] = [];
+	const validNameSegment = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+	async function walk(currentDir: string, parentSegments: string[], root = false): Promise<void> {
+		const entries = await fs.readdir(currentDir, { withFileTypes: true }).catch((error: unknown) => {
+			if (root && isEnoent(error)) {
+				diagnostics.push({
+					source,
+					type: "command",
+					status: "skipped_absent_source",
+					message: `no commands dir at ${dir}`,
+				});
+			} else if (!isEnoent(error)) {
+				diagnostics.push({
+					source,
+					type: "command",
+					status: "failed_io",
+					message: `failed to read ${currentDir}: ${(error as Error).message}`,
+				});
+			}
+			return undefined;
+		});
+		if (!entries) return;
+
+		for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+			if (entry.name.startsWith(".")) continue;
+			const entryPath = path.join(currentDir, entry.name);
+			if (entry.isDirectory()) {
+				if (options.recursive) await walk(entryPath, [...parentSegments, entry.name]);
+				continue;
+			}
+			if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+
+			const nameParts = [...parentSegments, entry.name.slice(0, -3)];
+			if (!nameParts.every(part => validNameSegment.test(part))) {
+				diagnostics.push({
+					source,
+					type: "command",
+					status: "failed_invalid_source",
+					message: `unsupported slash-command path ${path.relative(dir, entryPath)}; names must use letters, numbers, dots, underscores, or hyphens`,
+				});
+				continue;
+			}
+
+			const read = await readSourceText(entryPath, source, "command");
+			if ("diagnostic" in read) {
+				diagnostics.push(read.diagnostic);
+				continue;
+			}
+			candidates.push({ source, name: nameParts.join(":"), content: read.text });
+		}
+	}
+
+	await walk(dir, [], true);
+	return { candidates, diagnostics };
+}
+
 /**
  * Recursively collect skill candidates from any `**​/SKILL.md` under `root`.
  * The slug derives from the directory that directly contains the `SKILL.md`.

package/src/migrate/adapters/opencode.ts

@@ -21,8 +21,12 @@ export const opencodeAdapter: Adapter = {
 		const result: AdapterResult = {
 			mcpCandidates: [],
 			skillCandidates: [],
+			slashCommandCandidates: [],
+			agentCandidates: [],
 			instructionCandidates: [],
+			hookCandidates: [],
 			diagnostics: [],
+			manualActions: [],
 		};
 		const baseDir = path.join(homeDir, ".config", "opencode");