@gajae-code/coding-agent 0.6.4 → 0.7.0

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 };
+}

package/src/migrate/adapters/opencode.ts

@@ -0,0 +1,52 @@
+/**
+ * OpenCode adapter: reads `~/.config/opencode/opencode.json` (mcp), plus
+ * `~/.config/opencode/skills` and `~/.config/opencode/commands`.
+ */
+import * as path from "node:path";
+import type { AdapterResult, McpCandidate } from "../types";
+import {
+	type Adapter,
+	type AdapterOptions,
+	collectMarkdownPrompts,
+	collectSkillTree,
+	parseSourceJson,
+	readSourceText,
+} from "./index";
+
+const SOURCE = "opencode" as const;
+
+export const opencodeAdapter: Adapter = {
+	source: SOURCE,
+	async collect({ homeDir }: AdapterOptions): Promise<AdapterResult> {
+		const result: AdapterResult = { mcpCandidates: [], skillCandidates: [], diagnostics: [] };
+		const baseDir = path.join(homeDir, ".config", "opencode");
+
+		const configPath = path.join(baseDir, "opencode.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.mcp;
+				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 collectSkillTree(path.join(baseDir, "skills"), SOURCE);
+		result.skillCandidates.push(...skills.candidates);
+		result.diagnostics.push(...skills.diagnostics);
+
+		const commands = await collectMarkdownPrompts(path.join(baseDir, "commands"), SOURCE);
+		result.skillCandidates.push(...commands.candidates);
+		result.diagnostics.push(...commands.diagnostics);
+
+		return result;
+	},
+};

package/src/migrate/executor.ts

@@ -0,0 +1,81 @@
+/**
+ * Execute planned migration actions.
+ *
+ * Consumes the planner's actions unchanged and performs only `create`/`update`
+ * operations. It never re-plans. Writes are not transactional: on a write error
+ * the offending action flips to `failed_io`, already-written actions remain, and
+ * remaining actions still run (no rollback). Dry-run never calls this.
+ */
+import * as fsSync from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { upsertMCPServer } from "../runtime-mcp/config-writer";
+import type { MigrateAction } from "./types";
+
+async function ensureRealDirectoryPathNoFollow(directory: string): Promise<void> {
+	const resolved = path.resolve(directory);
+	const parsed = path.parse(resolved);
+	let current = parsed.root;
+	for (const part of resolved.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+		current = path.join(current, part);
+		try {
+			const stat = await fs.lstat(current);
+			if (!stat.isDirectory() || stat.isSymbolicLink()) {
+				throw new Error(`skill destination ancestor is not a real directory: ${current}`);
+			}
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			await fs.mkdir(current);
+			const stat = await fs.lstat(current);
+			if (!stat.isDirectory() || stat.isSymbolicLink()) {
+				throw new Error(`skill destination ancestor is not a real directory: ${current}`);
+			}
+		}
+	}
+}
+
+async function writeSkillFileNoFollow(destination: string, content: string): Promise<void> {
+	const skillDir = path.dirname(destination);
+	await ensureRealDirectoryPathNoFollow(skillDir);
+	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();
+	}
+}
+
+export async function executeActions(actions: MigrateAction[]): Promise<MigrateAction[]> {
+	const out: MigrateAction[] = [];
+	for (const action of actions) {
+		if (action.operation !== "create" && action.operation !== "update") {
+			out.push(action);
+			continue;
+		}
+		try {
+			if (action.type === "mcp" && action.mcp && action.name && action.destination) {
+				await upsertMCPServer(action.destination, action.name, action.mcp.config, {
+					force: action.operation === "update",
+				});
+				out.push(action);
+			} else if (action.type === "skill" && action.skill && action.destination) {
+				await writeSkillFileNoFollow(action.destination, action.skill.content);
+				out.push(action);
+			} else {
+				out.push(action);
+			}
+		} catch (error) {
+			out.push({
+				...action,
+				operation: "fail",
+				status: "failed_io",
+				reason: `write failed: ${(error as Error).message}`,
+			});
+		}
+	}
+	return out;
+}

package/src/migrate/mcp-mapper.ts

@@ -0,0 +1,152 @@
+/**
+ * Map raw source MCP server entries onto GJC `MCPServerConfig`.
+ *
+ * Implements the source-schema compatibility matrix from the consensus plan:
+ * preserved (P), transformed (T), omitted-with-warning (OW), skipped (S,
+ * `skipped_unmappable`), and failed (F, `failed_invalid_source`). Secret-indirection
+ * fields are always omitted-with-warning; their values are never read or emitted.
+ */
+import type { MCPServerConfig } from "../runtime-mcp/types";
+import type { MigrateSource } from "./types";
+
+export type McpMapOutcome =
+	| { ok: true; config: MCPServerConfig; warnings: string[] }
+	| { ok: false; status: "skipped_unmappable" | "failed_invalid_source"; reason: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asStringArray(value: unknown): string[] | undefined | "invalid" {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || !value.every(v => typeof v === "string")) return "invalid";
+	return value as string[];
+}
+
+function asStringRecord(value: unknown): Record<string, string> | undefined | "invalid" {
+	if (value === undefined) return undefined;
+	if (!isRecord(value) || !Object.values(value).every(v => typeof v === "string")) return "invalid";
+	return value as Record<string, string>;
+}
+
+/** Secret-indirection fields per source: always omitted-with-warning, never read. */
+const SECRET_INDIRECTION_FIELDS: Record<MigrateSource, string[]> = {
+	"claude-code": [],
+	codex: ["env_vars", "env_http_headers", "bearer_token_env_var"],
+	opencode: [],
+};
+
+/** Fields recognized for a source (handled or intentionally omitted). Anything else is omitted-with-warning. */
+const RECOGNIZED_FIELDS: Record<MigrateSource, ReadonlySet<string>> = {
+	"claude-code": new Set(["type", "command", "args", "env", "url", "headers", "enabled", "timeout", "cwd"]),
+	codex: new Set([
+		"type",
+		"command",
+		"args",
+		"env",
+		"url",
+		"http_headers",
+		"cwd",
+		"enabled",
+		"timeout",
+		"tool_timeout_sec",
+		// omitted-with-warning fields are still "recognized" (handled below):
+		"env_vars",
+		"env_http_headers",
+		"bearer_token_env_var",
+		"startup_timeout_sec",
+		"enabled_tools",
+		"disabled_tools",
+	]),
+	opencode: new Set(["type", "command", "args", "env", "url", "headers", "enabled", "timeout", "cwd"]),
+};
+
+/** Fields with no GJC equivalent: omitted-with-warning (named explicitly so the warning is precise). */
+const OMITTED_FIELDS: Record<MigrateSource, string[]> = {
+	"claude-code": [],
+	codex: ["startup_timeout_sec", "enabled_tools", "disabled_tools"],
+	opencode: [],
+};
+
+export function mapMcpEntry(source: MigrateSource, name: string, raw: unknown): McpMapOutcome {
+	if (!isRecord(raw)) {
+		return { ok: false, status: "failed_invalid_source", reason: `server "${name}" is not an object` };
+	}
+
+	const warnings: string[] = [];
+	for (const field of SECRET_INDIRECTION_FIELDS[source]) {
+		if (field in raw) warnings.push(`omitted secret-indirection field "${field}" for "${name}" (value not read)`);
+	}
+	for (const field of OMITTED_FIELDS[source]) {
+		if (field in raw) warnings.push(`omitted unsupported field "${field}" for "${name}"`);
+	}
+	// Unknown/unrecognized fields: omit-with-warning (never copy their values).
+	for (const field of Object.keys(raw)) {
+		if (!RECOGNIZED_FIELDS[source].has(field)) {
+			warnings.push(`omitted unknown field "${field}" for "${name}"`);
+		}
+	}
+
+	const rawType = typeof raw.type === "string" ? raw.type : undefined;
+	const command = typeof raw.command === "string" ? raw.command : undefined;
+	const url = typeof raw.url === "string" ? raw.url : undefined;
+
+	const base: { enabled?: boolean; timeout?: number } = {};
+	if (typeof raw.enabled === "boolean") base.enabled = raw.enabled;
+	if (typeof raw.timeout === "number") base.timeout = raw.timeout;
+	// Codex tool_timeout_sec -> timeout (ms).
+	if (source === "codex" && typeof raw.tool_timeout_sec === "number") {
+		base.timeout = raw.tool_timeout_sec * 1000;
+	}
+
+	const wantsStdio =
+		source === "opencode" ? rawType === "local" || (!rawType && !!command) : !!command || rawType === "stdio";
+	const wantsHttp =
+		source === "opencode"
+			? rawType === "remote" || rawType === "sse"
+			: rawType === "http" || rawType === "sse" || (!command && !!url);
+
+	if (wantsStdio) {
+		if (!command) {
+			return {
+				ok: false,
+				status: "skipped_unmappable",
+				reason: `server "${name}" has no command for stdio transport`,
+			};
+		}
+		const args = asStringArray(raw.args);
+		if (args === "invalid") {
+			return { ok: false, status: "failed_invalid_source", reason: `server "${name}" has invalid "args"` };
+		}
+		const env = asStringRecord(raw.env);
+		if (env === "invalid") {
+			return { ok: false, status: "failed_invalid_source", reason: `server "${name}" has invalid "env"` };
+		}
+		const config: MCPServerConfig = { type: "stdio", command, ...base };
+		if (args) config.args = args;
+		if (env) config.env = env;
+		if (typeof raw.cwd === "string") config.cwd = raw.cwd;
+		return { ok: true, config, warnings };
+	}
+
+	if (wantsHttp) {
+		if (!url) {
+			return {
+				ok: false,
+				status: "skipped_unmappable",
+				reason: `server "${name}" has no url for http/sse transport`,
+			};
+		}
+		const headerSource = source === "codex" ? raw.http_headers : raw.headers;
+		const headers = asStringRecord(headerSource);
+		if (headers === "invalid") {
+			return { ok: false, status: "failed_invalid_source", reason: `server "${name}" has invalid headers` };
+		}
+		const type = rawType === "sse" ? "sse" : "http";
+		const config = { type, url, ...base } as MCPServerConfig;
+		if (headers) (config as { headers?: Record<string, string> }).headers = headers;
+		return { ok: true, config, warnings };
+	}
+
+	return { ok: false, status: "skipped_unmappable", reason: `server "${name}" has neither a usable command nor url` };
+}

package/src/migrate/report.ts

@@ -0,0 +1,104 @@
+/**
+ * Build the human-readable and `--json` reports for `gjc migrate`.
+ *
+ * Secret values are never read upstream, so the report only ever contains field
+ * names in warnings — but rendering still treats action/warning text as opaque.
+ */
+import {
+	emptyStatusCounts,
+	isFailureStatus,
+	type MigrateAction,
+	type MigrateDestinations,
+	type MigrateReport,
+	type MigrateSource,
+	type MigrateWarning,
+	type StatusCounts,
+} from "./types";
+
+export interface BuildReportInput {
+	actions: MigrateAction[];
+	warnings: MigrateWarning[];
+	sources: MigrateSource[];
+	destinations: MigrateDestinations;
+	dryRun: boolean;
+	project: boolean;
+	force: boolean;
+}
+
+export function buildReport(input: BuildReportInput): MigrateReport {
+	const total = emptyStatusCounts();
+	const byType = { mcp: emptyStatusCounts(), skill: emptyStatusCounts(), source: emptyStatusCounts() };
+	const bySource = {} as Record<MigrateSource, StatusCounts>;
+	for (const source of input.sources) bySource[source] = emptyStatusCounts();
+
+	let ok = true;
+	for (const action of input.actions) {
+		total[action.status] += 1;
+		byType[action.type][action.status] += 1;
+		if (bySource[action.source]) bySource[action.source][action.status] += 1;
+		if (isFailureStatus(action.status)) ok = false;
+	}
+
+	return {
+		ok,
+		dryRun: input.dryRun,
+		project: input.project,
+		force: input.force,
+		sources: input.sources,
+		destinations: input.destinations,
+		summary: { total, byType, bySource },
+		actions: input.actions.map(action => ({
+			source: action.source,
+			type: action.type,
+			name: action.name,
+			effectiveName: action.effectiveName,
+			destination: action.destination,
+			operation: action.operation,
+			status: action.status,
+			reason: action.reason,
+			warnings: action.warnings,
+		})),
+		warnings: input.warnings,
+	};
+}
+
+function summarizeCounts(counts: StatusCounts): string {
+	const parts: string[] = [];
+	for (const [status, count] of Object.entries(counts)) {
+		if (count > 0) parts.push(`${status}=${count}`);
+	}
+	return parts.length > 0 ? parts.join(", ") : "nothing";
+}
+
+export function renderHuman(report: MigrateReport): string {
+	const lines: 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("");
+	lines.push(`MCP:    ${summarizeCounts(report.summary.byType.mcp)}`);
+	lines.push(`Skills: ${summarizeCounts(report.summary.byType.skill)}`);
+	if (Object.values(report.summary.byType.source).some(n => n > 0)) {
+		lines.push(`Source: ${summarizeCounts(report.summary.byType.source)}`);
+	}
+
+	const failures = report.actions.filter(a => isFailureStatus(a.status));
+	if (failures.length > 0) {
+		lines.push("");
+		lines.push("Failures:");
+		for (const f of failures) {
+			lines.push(`  - [${f.source}] ${f.type} ${f.name ?? ""}: ${f.status}${f.reason ? ` (${f.reason})` : ""}`);
+		}
+	}
+
+	if (report.warnings.length > 0) {
+		lines.push("");
+		lines.push("Warnings:");
+		for (const w of report.warnings) {
+			lines.push(`  - [${w.source}] ${w.type} ${w.name ?? ""}: ${w.message}`);
+		}
+	}
+
+	return lines.join("\n");
+}