@gajae-code/coding-agent 0.6.3 → 0.6.5

package/src/migrate/action-planner.ts

@@ -0,0 +1,318 @@
+/**
+ * Central migration action planner.
+ *
+ * Reads destination state ONCE and produces an immutable list of actions that
+ * both dry-run and live execution consume unchanged. This is the single place
+ * that decides add/update/skip/fail, destinations, and warnings, guaranteeing
+ * dry-run/live parity.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent, parseFrontmatter } from "@gajae-code/utils";
+import { readMCPConfigFile, validateServerName } from "../runtime-mcp/config-writer";
+import { mapMcpEntry } from "./mcp-mapper";
+import { slugify } from "./skill-normalizer";
+import type { AdapterResult, MigrateAction, MigrateDestinations, MigrateWarning } from "./types";
+
+export interface PlanInput {
+	results: AdapterResult[];
+	destinations: MigrateDestinations;
+	force: boolean;
+}
+
+export interface PlanOutput {
+	actions: MigrateAction[];
+	warnings: MigrateWarning[];
+}
+
+interface DestSkillIndex {
+	/** slug -> kind of existing destination entry. */
+	slugs: Map<string, "dir-with-skill" | "stale-dir" | "occupied">;
+	/** effective loaded name -> owning slug. */
+	effectiveNames: Map<string, string>;
+	/** The skills root exists but is unsafe to write through. */
+	rootUnsafe?: boolean;
+}
+
+async function indexDestinationSkills(skillsDir: string): Promise<DestSkillIndex> {
+	const index: DestSkillIndex = { slugs: new Map(), effectiveNames: new Map() };
+	let rootStat: Awaited<ReturnType<typeof fs.lstat>>;
+	try {
+		rootStat = await fs.lstat(skillsDir);
+	} catch (error) {
+		if (isEnoent(error)) return index;
+		throw error;
+	}
+	if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) return { ...index, rootUnsafe: true };
+	const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+	for (const entry of entries) {
+		const name = String(entry.name);
+		if (!entry.isDirectory() || entry.isSymbolicLink()) {
+			index.slugs.set(name, "occupied");
+			continue;
+		}
+		const slug = name;
+		const skillFile = path.join(skillsDir, slug, "SKILL.md");
+		let content: string | undefined;
+		try {
+			const skillFileStat = await fs.lstat(skillFile);
+			if (!skillFileStat.isFile() || skillFileStat.isSymbolicLink()) {
+				index.slugs.set(slug, "occupied");
+				continue;
+			}
+			content = await fs.readFile(skillFile, "utf-8");
+		} catch (error) {
+			if (isEnoent(error)) {
+				index.slugs.set(slug, "stale-dir");
+				continue;
+			}
+			throw error;
+		}
+		index.slugs.set(slug, "dir-with-skill");
+		const { frontmatter } = parseFrontmatter(content, { level: "off" });
+		const effective =
+			typeof frontmatter.name === "string" && frontmatter.name.trim() ? slugify(frontmatter.name) : slug;
+		index.effectiveNames.set(effective, slug);
+	}
+	return index;
+}
+
+export async function planMigration(input: PlanInput): Promise<PlanOutput> {
+	const actions: MigrateAction[] = [];
+	const warnings: MigrateWarning[] = [];
+
+	// 1. Source-level diagnostics become `source`-typed actions.
+	for (const result of input.results) {
+		for (const diag of result.diagnostics) {
+			actions.push({
+				source: diag.source,
+				type: "source",
+				operation: diag.status.startsWith("failed") ? "fail" : "skip",
+				status: diag.status,
+				reason: diag.message,
+			});
+		}
+	}
+
+	// 2. MCP actions — read the destination config once.
+	const existingConfig = await readMCPConfigFile(input.destinations.mcpConfigPath).catch(() => null);
+	const mcpInvalid = existingConfig === null;
+	const existingServers = new Set(Object.keys(existingConfig?.mcpServers ?? {}));
+	const disabledServers = new Set(existingConfig?.disabledServers ?? []);
+
+	for (const result of input.results) {
+		for (const candidate of result.mcpCandidates) {
+			const nameError = validateServerName(candidate.name);
+			if (nameError) {
+				actions.push({
+					source: candidate.source,
+					type: "mcp",
+					name: candidate.name,
+					operation: "fail",
+					status: "failed_invalid_source",
+					reason: nameError,
+				});
+				continue;
+			}
+			const mapped = mapMcpEntry(candidate.source, candidate.name, candidate.raw);
+			if (!mapped.ok) {
+				actions.push({
+					source: candidate.source,
+					type: "mcp",
+					name: candidate.name,
+					operation: mapped.status.startsWith("failed") ? "fail" : "skip",
+					status: mapped.status,
+					reason: mapped.reason,
+				});
+				continue;
+			}
+			for (const w of mapped.warnings)
+				warnings.push({ source: candidate.source, type: "mcp", name: candidate.name, message: w });
+
+			if (mcpInvalid) {
+				actions.push({
+					source: candidate.source,
+					type: "mcp",
+					name: candidate.name,
+					destination: input.destinations.mcpConfigPath,
+					operation: "fail",
+					status: "failed_invalid_destination",
+					reason: "destination mcp.json is malformed",
+				});
+				continue;
+			}
+
+			const exists = existingServers.has(candidate.name);
+			if (exists && !input.force) {
+				actions.push({
+					source: candidate.source,
+					type: "mcp",
+					name: candidate.name,
+					destination: input.destinations.mcpConfigPath,
+					operation: "skip",
+					status: "skipped_exists",
+				});
+				continue;
+			}
+			const actionWarnings = [...mapped.warnings];
+			if (exists && disabledServers.has(candidate.name)) {
+				const msg = `disabled MCP state preserved for "${candidate.name}"`;
+				actionWarnings.push(msg);
+				warnings.push({ source: candidate.source, type: "mcp", name: candidate.name, message: msg });
+			}
+			actions.push({
+				source: candidate.source,
+				type: "mcp",
+				name: candidate.name,
+				destination: input.destinations.mcpConfigPath,
+				operation: exists ? "update" : "create",
+				status: exists ? "updated" : "imported",
+				warnings: actionWarnings.length > 0 ? actionWarnings : undefined,
+				mcp: { config: mapped.config, force: input.force },
+			});
+			// Track so an intra-run duplicate of the same name doesn't double-write.
+			existingServers.add(candidate.name);
+		}
+	}
+
+	// 3. Skill actions — index the destination skills tree once.
+	const destIndex = await indexDestinationSkills(input.destinations.skillsDir);
+	const plannedSlugs = new Map<string, string>(); // slug -> source (intra-run)
+	const plannedEffective = new Map<string, string>(); // effective -> slug (intra-run)
+
+	for (const result of input.results) {
+		for (const candidate of result.skillCandidates) {
+			for (const w of candidate.warnings) {
+				warnings.push({ source: candidate.source, type: "skill", name: candidate.slug, message: w });
+			}
+			const slug = candidate.slug;
+			const destination = path.join(input.destinations.skillsDir, slug, "SKILL.md");
+			const base = {
+				source: candidate.source,
+				type: "skill" as const,
+				name: slug,
+				effectiveName: slug,
+				destination,
+			};
+
+			// Intra-run duplicate slug / effective name. Since effective name == slug, a
+			// duplicate always targets the same destination: skip by default; with --force
+			// the later (canonical-order) source overwrites the same destination.
+			if (plannedSlugs.has(slug) || plannedEffective.has(slug)) {
+				if (input.force) {
+					actions.push({
+						...base,
+						operation: "update",
+						status: "updated",
+						reason: "duplicate within this run (overwritten under --force)",
+						skill: { content: candidate.content },
+					});
+				} else {
+					actions.push({
+						...base,
+						operation: "skip",
+						status: "skipped_exists",
+						reason: "duplicate within this run",
+					});
+				}
+				continue;
+			}
+
+			const existingKind = destIndex.slugs.get(slug);
+			const effectiveOwner = destIndex.effectiveNames.get(slug);
+
+			if (destIndex.rootUnsafe) {
+				if (!input.force) {
+					actions.push({
+						...base,
+						operation: "skip",
+						status: "skipped_exists",
+						reason: "skills destination root is not a real directory",
+					});
+				} else {
+					actions.push({
+						...base,
+						operation: "fail",
+						status: "failed_invalid_destination",
+						reason: "skills destination root is not a real directory; refusing to write",
+					});
+				}
+				continue;
+			}
+
+			// Effective-name collision with a different existing destination skill.
+			if (effectiveOwner && effectiveOwner !== slug) {
+				if (!input.force) {
+					actions.push({
+						...base,
+						operation: "skip",
+						status: "skipped_exists",
+						reason: `effective name collides with "${effectiveOwner}"`,
+					});
+				} else {
+					actions.push({
+						...base,
+						operation: "fail",
+						status: "failed_invalid_destination",
+						reason: `effective name collides with "${effectiveOwner}"`,
+					});
+				}
+				continue;
+			}
+
+			if (existingKind === "occupied") {
+				if (!input.force) {
+					actions.push({
+						...base,
+						operation: "skip",
+						status: "skipped_exists",
+						reason: "a non-directory or unsafe file occupies the destination path",
+					});
+				} else {
+					actions.push({
+						...base,
+						operation: "fail",
+						status: "failed_invalid_destination",
+						reason: "a non-directory or unsafe file occupies the destination path; refusing to delete",
+					});
+				}
+				continue;
+			}
+
+			if (existingKind === "dir-with-skill") {
+				if (!input.force) {
+					actions.push({ ...base, operation: "skip", status: "skipped_exists" });
+				} else {
+					actions.push({ ...base, operation: "update", status: "updated", skill: { content: candidate.content } });
+				}
+				plannedSlugs.set(slug, candidate.source);
+				plannedEffective.set(slug, slug);
+				continue;
+			}
+
+			if (existingKind === "stale-dir") {
+				if (!input.force) {
+					actions.push({ ...base, operation: "skip", status: "skipped_exists", reason: "stale skill directory" });
+				} else {
+					actions.push({
+						...base,
+						operation: "update",
+						status: "updated",
+						reason: "stale skill directory reused",
+						skill: { content: candidate.content },
+					});
+				}
+				plannedSlugs.set(slug, candidate.source);
+				plannedEffective.set(slug, slug);
+				continue;
+			}
+
+			// Fresh import.
+			actions.push({ ...base, operation: "create", status: "imported", skill: { content: candidate.content } });
+			plannedSlugs.set(slug, candidate.source);
+			plannedEffective.set(slug, slug);
+		}
+	}
+
+	return { actions, warnings };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Claude Code adapter: reads `~/.claude.json` (mcpServers) and `~/.claude/skills`.
+ */
+import * as path from "node:path";
+import type { AdapterResult, McpCandidate } from "../types";
+import { type Adapter, type AdapterOptions, collectSkillDir, parseSourceJson, readSourceText } from "./index";
+
+const SOURCE = "claude-code" as const;
+
+export const claudeCodeAdapter: Adapter = {
+	source: SOURCE,
+	async collect({ homeDir }: AdapterOptions): Promise<AdapterResult> {
+		const result: AdapterResult = { mcpCandidates: [], skillCandidates: [], diagnostics: [] };
+
+		const configPath = path.join(homeDir, ".claude.json");
+		const read = await readSourceText(configPath, SOURCE, "mcp");
+		if ("diagnostic" in read) {
+			result.diagnostics.push(read.diagnostic);
+		} else {
+			const parsed = parseSourceJson(read.text, configPath, SOURCE, "mcp");
+			if ("diagnostic" in parsed) {
+				result.diagnostics.push(parsed.diagnostic);
+			} else {
+				const servers = parsed.data.mcpServers;
+				if (servers && typeof servers === "object" && !Array.isArray(servers)) {
+					for (const [name, raw] of Object.entries(servers as Record<string, unknown>)) {
+						result.mcpCandidates.push({ source: SOURCE, name, raw } satisfies McpCandidate);
+					}
+				}
+			}
+		}
+
+		const skills = await collectSkillDir(path.join(homeDir, ".claude", "skills"), SOURCE);
+		result.skillCandidates.push(...skills.candidates);
+		result.diagnostics.push(...skills.diagnostics);
+
+		return result;
+	},
+};

package/src/migrate/adapters/codex.ts

@@ -0,0 +1,70 @@
+/**
+ * Codex adapter: reads `~/.codex/config.toml` ([mcp_servers]) and `~/.codex/prompts`.
+ */
+
+import * as path from "node:path";
+import { TOML } from "bun";
+import type { AdapterResult, McpCandidate, SourceDiagnostic } from "../types";
+import { type Adapter, type AdapterOptions, collectMarkdownPrompts, readSourceText } from "./index";
+
+const SOURCE = "codex" as const;
+
+function parseToml(
+	text: string,
+	filePath: string,
+): { data: Record<string, unknown> } | { diagnostic: SourceDiagnostic } {
+	try {
+		const data = TOML.parse(text) as unknown;
+		if (typeof data !== "object" || data === null) {
+			return {
+				diagnostic: {
+					source: SOURCE,
+					type: "mcp",
+					status: "failed_invalid_source",
+					message: `${filePath} is not a TOML table`,
+				},
+			};
+		}
+		return { data: data as Record<string, unknown> };
+	} catch (error) {
+		return {
+			diagnostic: {
+				source: SOURCE,
+				type: "mcp",
+				status: "failed_invalid_source",
+				message: `invalid TOML in ${filePath}: ${(error as Error).message}`,
+			},
+		};
+	}
+}
+
+export const codexAdapter: Adapter = {
+	source: SOURCE,
+	async collect({ homeDir }: AdapterOptions): Promise<AdapterResult> {
+		const result: AdapterResult = { mcpCandidates: [], skillCandidates: [], diagnostics: [] };
+
+		const configPath = path.join(homeDir, ".codex", "config.toml");
+		const read = await readSourceText(configPath, SOURCE, "mcp");
+		if ("diagnostic" in read) {
+			result.diagnostics.push(read.diagnostic);
+		} else {
+			const parsed = parseToml(read.text, configPath);
+			if ("diagnostic" in parsed) {
+				result.diagnostics.push(parsed.diagnostic);
+			} else {
+				const servers = parsed.data.mcp_servers;
+				if (servers && typeof servers === "object" && !Array.isArray(servers)) {
+					for (const [name, raw] of Object.entries(servers as Record<string, unknown>)) {
+						result.mcpCandidates.push({ source: SOURCE, name, raw } satisfies McpCandidate);
+					}
+				}
+			}
+		}
+
+		const prompts = await collectMarkdownPrompts(path.join(homeDir, ".codex", "prompts"), SOURCE);
+		result.skillCandidates.push(...prompts.candidates);
+		result.diagnostics.push(...prompts.diagnostics);
+
+		return result;
+	},
+};

package/src/migrate/adapters/index.ts

@@ -0,0 +1,277 @@
+/**
+ * Source adapters for `gjc migrate`.
+ *
+ * Each adapter reads GLOBAL/home config for one source agent and returns
+ * normalized MCP + skill candidates plus source-level diagnostics. Adapters never
+ * read project-level config and never connect to anything.
+ */
+import * as fs from "node:fs/promises";
+import { isEnoent } from "@gajae-code/utils";
+import { normalizeSkill } from "../skill-normalizer";
+import type { AdapterResult, MigrateSource, SkillCandidate, SourceDiagnostic } from "../types";
+import { claudeCodeAdapter } from "./claude-code";
+import { codexAdapter } from "./codex";
+import { opencodeAdapter } from "./opencode";
+
+export interface AdapterOptions {
+	/** Home directory root; overridable for tests. */
+	homeDir: string;
+}
+
+export interface Adapter {
+	source: MigrateSource;
+	collect(options: AdapterOptions): Promise<AdapterResult>;
+}
+
+const ADAPTERS: Record<MigrateSource, Adapter> = {
+	"claude-code": claudeCodeAdapter,
+	codex: codexAdapter,
+	opencode: opencodeAdapter,
+};
+
+export function getAdapter(source: MigrateSource): Adapter {
+	return ADAPTERS[source];
+}
+
+/** Read a text file, classifying absence/IO errors into source diagnostics. */
+export async function readSourceText(
+	filePath: string,
+	source: MigrateSource,
+	type: SourceDiagnostic["type"],
+): Promise<{ text: string } | { diagnostic: SourceDiagnostic }> {
+	try {
+		return { text: await fs.readFile(filePath, "utf-8") };
+	} catch (error) {
+		if (isEnoent(error)) {
+			return {
+				diagnostic: { source, type, status: "skipped_absent_source", message: `no ${type} config at ${filePath}` },
+			};
+		}
+		return {
+			diagnostic: {
+				source,
+				type,
+				status: "failed_io",
+				message: `failed to read ${filePath}: ${(error as Error).message}`,
+			},
+		};
+	}
+}
+
+/** Parse JSON text, classifying parse errors into a `failed_invalid_source` diagnostic. */
+export function parseSourceJson(
+	text: string,
+	filePath: string,
+	source: MigrateSource,
+	type: SourceDiagnostic["type"],
+): { data: Record<string, unknown> } | { diagnostic: SourceDiagnostic } {
+	try {
+		const data = JSON.parse(text) as unknown;
+		if (typeof data !== "object" || data === null) {
+			return {
+				diagnostic: { source, type, status: "failed_invalid_source", message: `${filePath} is not a JSON object` },
+			};
+		}
+		return { data: data as Record<string, unknown> };
+	} catch (error) {
+		return {
+			diagnostic: {
+				source,
+				type,
+				status: "failed_invalid_source",
+				message: `invalid JSON in ${filePath}: ${(error as Error).message}`,
+			},
+		};
+	}
+}
+
+/**
+ * Collect skill candidates from a directory of `<name>/SKILL.md` entries.
+ * A missing directory yields a `skipped_absent_source` diagnostic.
+ */
+export async function collectSkillDir(
+	dir: string,
+	source: MigrateSource,
+): Promise<{ candidates: SkillCandidate[]; diagnostics: SourceDiagnostic[] }> {
+	const candidates: SkillCandidate[] = [];
+	const diagnostics: SourceDiagnostic[] = [];
+	let entries: string[];
+	try {
+		const dirents = await fs.readdir(dir, { withFileTypes: true });
+		entries = dirents.filter(d => d.isDirectory()).map(d => d.name);
+	} catch (error) {
+		if (isEnoent(error)) {
+			diagnostics.push({
+				source,
+				type: "skill",
+				status: "skipped_absent_source",
+				message: `no skills dir at ${dir}`,
+			});
+		} else {
+			diagnostics.push({
+				source,
+				type: "skill",
+				status: "failed_io",
+				message: `failed to read ${dir}: ${(error as Error).message}`,
+			});
+		}
+		return { candidates, diagnostics };
+	}
+
+	for (const name of entries.sort()) {
+		const skillFile = `${dir}/${name}/SKILL.md`;
+		const read = await readSourceText(skillFile, source, "skill");
+		if ("diagnostic" in read) {
+			// A subdir without SKILL.md is simply not a skill; only surface non-absent errors.
+			if (read.diagnostic.status !== "skipped_absent_source") diagnostics.push(read.diagnostic);
+			continue;
+		}
+		try {
+			const normalized = normalizeSkill({ rawName: name, content: read.text });
+			candidates.push({ source, slug: normalized.slug, content: normalized.content, warnings: normalized.warnings });
+		} catch (error) {
+			diagnostics.push({
+				source,
+				type: "skill",
+				status: "failed_invalid_source",
+				message: `failed to normalize skill ${skillFile}: ${(error as Error).message}`,
+			});
+		}
+	}
+	return { candidates, diagnostics };
+}
+
+/**
+ * Collect skill candidates from a flat directory of `*.md` prompt/command files.
+ */
+export async function collectMarkdownPrompts(
+	dir: string,
+	source: MigrateSource,
+): Promise<{ candidates: SkillCandidate[]; diagnostics: SourceDiagnostic[] }> {
+	const candidates: SkillCandidate[] = [];
+	const diagnostics: SourceDiagnostic[] = [];
+	let files: string[];
+	try {
+		const dirents = await fs.readdir(dir, { withFileTypes: true });
+		files = dirents.filter(d => d.isFile() && d.name.endsWith(".md")).map(d => d.name);
+	} catch (error) {
+		if (isEnoent(error)) {
+			diagnostics.push({
+				source,
+				type: "skill",
+				status: "skipped_absent_source",
+				message: `no prompts dir at ${dir}`,
+			});
+		} else {
+			diagnostics.push({
+				source,
+				type: "skill",
+				status: "failed_io",
+				message: `failed to read ${dir}: ${(error as Error).message}`,
+			});
+		}
+		return { candidates, diagnostics };
+	}
+
+	for (const file of files.sort()) {
+		const promptFile = `${dir}/${file}`;
+		const read = await readSourceText(promptFile, source, "skill");
+		if ("diagnostic" in read) {
+			diagnostics.push(read.diagnostic);
+			continue;
+		}
+		const rawName = file.replace(/\.md$/, "");
+		try {
+			const normalized = normalizeSkill({ rawName, content: read.text });
+			candidates.push({ source, slug: normalized.slug, content: normalized.content, warnings: normalized.warnings });
+		} catch (error) {
+			diagnostics.push({
+				source,
+				type: "skill",
+				status: "failed_invalid_source",
+				message: `failed to convert prompt ${promptFile}: ${(error as Error).message}`,
+			});
+		}
+	}
+	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`.
+ */
+export async function collectSkillTree(
+	root: string,
+	source: MigrateSource,
+): Promise<{ candidates: SkillCandidate[]; diagnostics: SourceDiagnostic[] }> {
+	const candidates: SkillCandidate[] = [];
+	const diagnostics: SourceDiagnostic[] = [];
+
+	async function walk(dir: string): Promise<void> {
+		const entries = await fs.readdir(dir, { withFileTypes: true }).catch((error: unknown) => {
+			if (isEnoent(error)) return null;
+			diagnostics.push({
+				source,
+				type: "skill",
+				status: "failed_io",
+				message: `failed to read ${dir}: ${(error as Error).message}`,
+			});
+			return null;
+		});
+		if (!entries) return;
+
+		const hasSkill = entries.some(e => e.isFile() && String(e.name) === "SKILL.md");
+		if (hasSkill) {
+			const skillFile = `${dir}/SKILL.md`;
+			const read = await readSourceText(skillFile, source, "skill");
+			if ("diagnostic" in read) {
+				if (read.diagnostic.status !== "skipped_absent_source") diagnostics.push(read.diagnostic);
+			} else {
+				try {
+					const rawName = dir.split("/").pop() ?? dir;
+					const normalized = normalizeSkill({ rawName, content: read.text });
+					candidates.push({
+						source,
+						slug: normalized.slug,
+						content: normalized.content,
+						warnings: normalized.warnings,
+					});
+				} catch (error) {
+					diagnostics.push({
+						source,
+						type: "skill",
+						status: "failed_invalid_source",
+						message: `failed to normalize skill ${skillFile}: ${(error as Error).message}`,
+					});
+				}
+			}
+		}
+
+		for (const entry of entries) {
+			if (entry.isDirectory()) await walk(`${dir}/${String(entry.name)}`);
+		}
+	}
+
+	// Surface an absent root the same way the flat collectors do.
+	const rootEntries = await fs.readdir(root).catch((error: unknown) => {
+		if (isEnoent(error)) {
+			diagnostics.push({
+				source,
+				type: "skill",
+				status: "skipped_absent_source",
+				message: `no skills dir at ${root}`,
+			});
+		} else {
+			diagnostics.push({
+				source,
+				type: "skill",
+				status: "failed_io",
+				message: `failed to read ${root}: ${(error as Error).message}`,
+			});
+		}
+		return null;
+	});
+	if (rootEntries) await walk(root);
+
+	return { candidates, diagnostics };
+}