oh-my-codex 0.14.4 → 0.15.1

package/src/scripts/sync-plugin-mirror.ts

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import process from "node:process";
+import {
+	getSetupInstallableSkillNames,
+	isCatalogInstallableStatus,
+} from "../catalog/installable.js";
+import { readCatalogManifest } from "../catalog/reader.js";
+import {
+	assertSkillMirror,
+	compareSkillMirror,
+} from "../catalog/skill-mirror.js";
+import { buildOmxPluginMcpManifest } from "../config/omx-first-party-mcp.js";
+
+export interface SyncPluginMirrorOptions {
+	root?: string;
+	check?: boolean;
+	verbose?: boolean;
+}
+
+export interface SyncPluginMirrorResult {
+	checked: boolean;
+	mirroredSkillNames: string[];
+	changed: boolean;
+}
+
+type JsonValue =
+	| null
+	| boolean
+	| number
+	| string
+	| JsonValue[]
+	| { [key: string]: JsonValue };
+
+type PluginManifest = {
+	name?: string;
+	version?: string;
+	skills?: string;
+	mcpServers?: string;
+	apps?: string;
+	agents?: string;
+	prompts?: string;
+	hooks?: string;
+	[key: string]: JsonValue | undefined;
+};
+
+type PackageJson = {
+	version?: string;
+};
+
+const PLUGIN_NAME = "oh-my-codex";
+const SETUP_OWNED_PLUGIN_MANIFEST_FIELDS = [
+	"agents",
+	"prompts",
+	"hooks",
+] as const;
+
+async function readJsonFile<T>(path: string): Promise<T> {
+	return JSON.parse(await readFile(path, "utf-8")) as T;
+}
+
+function stringifyJson(value: unknown): string {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function assertDeepJsonEqual(
+	actual: unknown,
+	expected: unknown,
+	label: string,
+): void {
+	const actualJson = stringifyJson(actual);
+	const expectedJson = stringifyJson(expected);
+	if (actualJson !== expectedJson) {
+		throw new Error(
+			[
+				"plugin_bundle_metadata_out_of_sync",
+				`kind=${label}`,
+				`expected=${expectedJson.trim()}`,
+				`actual=${actualJson.trim()}`,
+			].join("\n"),
+		);
+	}
+}
+
+function getPluginPaths(root: string): {
+	pluginRoot: string;
+	pluginSkillsDir: string;
+	pluginMcpPath: string;
+	pluginAppsPath: string;
+	pluginManifestPath: string;
+} {
+	const pluginRoot = join(root, "plugins", PLUGIN_NAME);
+	return {
+		pluginRoot,
+		pluginSkillsDir: join(pluginRoot, "skills"),
+		pluginMcpPath: join(pluginRoot, ".mcp.json"),
+		pluginAppsPath: join(pluginRoot, ".app.json"),
+		pluginManifestPath: join(pluginRoot, ".codex-plugin", "plugin.json"),
+	};
+}
+
+async function assertRootSkillCatalogConsistency(
+	root: string,
+	skillNames: readonly string[],
+): Promise<void> {
+	const manifest = readCatalogManifest(root);
+	const rootSkillsDir = join(root, "skills");
+	const manifestByName = new Map(
+		manifest.skills.map((skill) => [skill.name, skill]),
+	);
+	const expectedSkillNames = new Set(skillNames);
+
+	for (const skillName of skillNames) {
+		const skillMd = join(rootSkillsDir, skillName, "SKILL.md");
+		if (!existsSync(skillMd)) {
+			throw new Error(`canonical_skill_missing: skills/${skillName}/SKILL.md`);
+		}
+	}
+
+	const rootEntries = await readdir(rootSkillsDir, { withFileTypes: true });
+	const unlistedSkillDirs = rootEntries
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => entry.name)
+		.filter(
+			(skillName) =>
+				!manifestByName.has(skillName) && !expectedSkillNames.has(skillName),
+		)
+		.sort();
+	if (unlistedSkillDirs.length > 0) {
+		throw new Error(
+			[
+				"canonical_skill_catalog_out_of_sync",
+				"message=root skill directories must be listed in the catalog or explicitly included by setup policy",
+				`skills=${JSON.stringify(unlistedSkillDirs)}`,
+			].join("\n"),
+		);
+	}
+
+	const nonInstallableRootSkillDirs = rootEntries
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => entry.name)
+		.filter((skillName) => {
+			if (expectedSkillNames.has(skillName)) return false;
+			const status = manifestByName.get(skillName)?.status;
+			return status !== "alias" && status !== "merged";
+		})
+		.sort();
+	if (nonInstallableRootSkillDirs.length > 0) {
+		throw new Error(
+			[
+				"canonical_skill_catalog_out_of_sync",
+				"message=root skill directories excluded from plugin must be alias or merged catalog entries",
+				`skills=${JSON.stringify(nonInstallableRootSkillDirs)}`,
+			].join("\n"),
+		);
+	}
+
+	const installableMissingFromSetup = manifest.skills
+		.filter((skill) => isCatalogInstallableStatus(skill.status))
+		.map((skill) => skill.name)
+		.filter((skillName) => !expectedSkillNames.has(skillName))
+		.sort();
+	if (installableMissingFromSetup.length > 0) {
+		throw new Error(
+			[
+				"canonical_skill_catalog_out_of_sync",
+				"message=installable catalog skills must be included in plugin/setup installable skill set",
+				`skills=${JSON.stringify(installableMissingFromSetup)}`,
+			].join("\n"),
+		);
+	}
+}
+
+async function buildExpectedPluginManifest(
+	root: string,
+): Promise<PluginManifest> {
+	const { pluginManifestPath } = getPluginPaths(root);
+	const [manifest, pkg] = await Promise.all([
+		readJsonFile<PluginManifest>(pluginManifestPath),
+		readJsonFile<PackageJson>(join(root, "package.json")),
+	]);
+	return {
+		...manifest,
+		name: PLUGIN_NAME,
+		version: pkg.version,
+		skills: "./skills/",
+		mcpServers: "./.mcp.json",
+		apps: "./.app.json",
+	};
+}
+
+async function assertPluginManifestPolicy(
+	root: string,
+	manifest: PluginManifest,
+): Promise<void> {
+	const pkg = await readJsonFile<PackageJson>(join(root, "package.json"));
+	const expectedFields: Pick<
+		PluginManifest,
+		"name" | "version" | "skills" | "mcpServers" | "apps"
+	> = {
+		name: PLUGIN_NAME,
+		version: pkg.version,
+		skills: "./skills/",
+		mcpServers: "./.mcp.json",
+		apps: "./.app.json",
+	};
+
+	for (const [field, expectedValue] of Object.entries(expectedFields)) {
+		if (manifest[field] !== expectedValue) {
+			throw new Error(
+				[
+					"plugin_bundle_metadata_out_of_sync",
+					"kind=plugin-manifest",
+					`field=${field}`,
+					`expected=${JSON.stringify(expectedValue)}`,
+					`actual=${JSON.stringify(manifest[field])}`,
+				].join("\n"),
+			);
+		}
+	}
+
+	for (const field of SETUP_OWNED_PLUGIN_MANIFEST_FIELDS) {
+		if (manifest[field] !== undefined) {
+			throw new Error(
+				[
+					"plugin_bundle_metadata_out_of_sync",
+					"kind=plugin-manifest",
+					`field=${field}`,
+					"message=setup-owned agents/prompts/hooks must not be plugin-scoped",
+				].join("\n"),
+			);
+		}
+	}
+}
+
+async function assertPluginMetadata(root: string): Promise<void> {
+	const { pluginMcpPath, pluginAppsPath, pluginManifestPath } =
+		getPluginPaths(root);
+	const [actualMcp, actualApps, actualManifest] = await Promise.all([
+		readJsonFile<unknown>(pluginMcpPath),
+		readJsonFile<unknown>(pluginAppsPath),
+		readJsonFile<PluginManifest>(pluginManifestPath),
+	]);
+
+	assertDeepJsonEqual(actualMcp, buildOmxPluginMcpManifest(), "mcp-manifest");
+	assertDeepJsonEqual(actualApps, { apps: {} }, "apps-manifest");
+	await assertPluginManifestPolicy(root, actualManifest);
+}
+
+async function writePluginMetadata(
+	root: string,
+	verbose = false,
+): Promise<boolean> {
+	const { pluginMcpPath, pluginAppsPath, pluginManifestPath } =
+		getPluginPaths(root);
+	const expectedMcp = buildOmxPluginMcpManifest();
+	const expectedApps = { apps: {} };
+	const expectedManifest = await buildExpectedPluginManifest(root);
+	const writes = [
+		{
+			path: pluginMcpPath,
+			content: stringifyJson(expectedMcp),
+			label: "plugin MCP manifest",
+		},
+		{
+			path: pluginAppsPath,
+			content: stringifyJson(expectedApps),
+			label: "plugin apps manifest",
+		},
+		{
+			path: pluginManifestPath,
+			content: stringifyJson(expectedManifest),
+			label: "plugin manifest",
+		},
+	];
+	let changed = false;
+
+	for (const write of writes) {
+		const existing = existsSync(write.path)
+			? await readFile(write.path, "utf-8")
+			: null;
+		if (existing !== write.content) {
+			await mkdir(dirname(write.path), { recursive: true });
+			await writeFile(write.path, write.content);
+			changed = true;
+			if (verbose) console.log(`synced ${write.label}`);
+		}
+	}
+
+	return changed;
+}
+
+export async function syncPluginMirror(
+	options: SyncPluginMirrorOptions = {},
+): Promise<SyncPluginMirrorResult> {
+	const root = options.root ?? process.cwd();
+	const manifest = readCatalogManifest(root);
+	const skillNames = [...getSetupInstallableSkillNames(manifest)].sort();
+	const rootSkillsDir = join(root, "skills");
+	const { pluginSkillsDir } = getPluginPaths(root);
+
+	await assertRootSkillCatalogConsistency(root, skillNames);
+
+	if (options.check) {
+		await assertSkillMirror(rootSkillsDir, pluginSkillsDir, skillNames);
+		await assertPluginMetadata(root);
+		return { checked: true, mirroredSkillNames: skillNames, changed: false };
+	}
+
+	const beforeSkillsMatch =
+		(await compareSkillMirror(rootSkillsDir, pluginSkillsDir, skillNames)) ===
+		null;
+
+	await rm(pluginSkillsDir, { recursive: true, force: true });
+	await mkdir(pluginSkillsDir, { recursive: true });
+
+	for (const skillName of skillNames) {
+		await cp(join(rootSkillsDir, skillName), join(pluginSkillsDir, skillName), {
+			recursive: true,
+		});
+		if (options.verbose) {
+			console.log(
+				`mirrored skills/${skillName} -> plugins/${PLUGIN_NAME}/skills/${skillName}`,
+			);
+		}
+	}
+
+	const metadataChanged = await writePluginMetadata(root, options.verbose);
+
+	await assertSkillMirror(rootSkillsDir, pluginSkillsDir, skillNames);
+	await assertPluginMetadata(root);
+	return {
+		checked: false,
+		mirroredSkillNames: skillNames,
+		changed: !beforeSkillsMatch || metadataChanged,
+	};
+}
+
+function parseArgs(argv: string[]): SyncPluginMirrorOptions {
+	return {
+		check: argv.includes("--check"),
+		verbose: argv.includes("--verbose"),
+	};
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	syncPluginMirror(parseArgs(process.argv.slice(2)))
+		.then((result) => {
+			const action = result.checked ? "verified" : "synced";
+			console.log(
+				`[sync-plugin-mirror] ${action} ${result.mirroredSkillNames.length} canonical skill director${result.mirroredSkillNames.length === 1 ? "y" : "ies"} and plugin metadata`,
+			);
+		})
+		.catch((error: unknown) => {
+			console.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+		});
+}

package/src/scripts/verify-native-agents.ts

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import process from "node:process";
+import TOML from "@iarna/toml";
+import { AGENT_DEFINITIONS, type AgentDefinition } from "../agents/definitions.js";
+import { generateAgentToml } from "../agents/native-config.js";
+import {
+  NON_NATIVE_AGENT_PROMPT_ASSETS,
+  assertNativeAgentCanonicalTargets,
+  getCatalogAgentByName,
+  getInstallableNativeAgentNames,
+  isNativeAgentInstallableStatus,
+} from "../agents/policy.js";
+import { readCatalogManifest } from "../catalog/reader.js";
+import type { CatalogManifest } from "../catalog/schema.js";
+
+export interface VerifyNativeAgentsOptions {
+  root?: string;
+  manifest?: CatalogManifest;
+  definitions?: Record<string, AgentDefinition>;
+  promptNames?: Set<string>;
+  pluginManifest?: Record<string, unknown>;
+}
+
+export interface VerifyNativeAgentsResult {
+  installableAgentNames: string[];
+  promptAssetNames: string[];
+}
+
+function errorBlock(code: string, fields: Record<string, unknown>): Error {
+  return new Error(
+    [
+      code,
+      ...Object.entries(fields).map(
+        ([key, value]) => `${key}=${JSON.stringify(value)}`,
+      ),
+    ].join("\n"),
+  );
+}
+
+async function readPromptNames(root: string): Promise<Set<string>> {
+  const promptsDir = join(root, "prompts");
+  const entries = await readdir(promptsDir, { withFileTypes: true });
+  return new Set(
+    entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+      .map((entry) => entry.name.slice(0, -3)),
+  );
+}
+
+async function readPluginManifest(
+  root: string,
+): Promise<Record<string, unknown> | null> {
+  const pluginManifestPath = join(
+    root,
+    "plugins",
+    "oh-my-codex",
+    ".codex-plugin",
+    "plugin.json",
+  );
+  if (!existsSync(pluginManifestPath)) return null;
+  return JSON.parse(await readFile(pluginManifestPath, "utf-8")) as Record<
+    string,
+    unknown
+  >;
+}
+
+function assertTomlStructure(
+  agentName: string,
+  agent: AgentDefinition,
+  toml: string,
+): void {
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = TOML.parse(toml) as Record<string, unknown>;
+  } catch (cause) {
+    throw errorBlock("native_agent_toml_invalid", {
+      agent: agentName,
+      message: cause instanceof Error ? cause.message : String(cause),
+    });
+  }
+
+  if (parsed.name !== agentName) {
+    throw errorBlock("native_agent_toml_invalid", {
+      agent: agentName,
+      field: "name",
+      expected: agentName,
+      actual: parsed.name,
+    });
+  }
+  if (parsed.description !== agent.description) {
+    throw errorBlock("native_agent_toml_invalid", {
+      agent: agentName,
+      field: "description",
+      expected: agent.description,
+      actual: parsed.description,
+    });
+  }
+  if (parsed.model_reasoning_effort !== agent.reasoningEffort) {
+    throw errorBlock("native_agent_toml_invalid", {
+      agent: agentName,
+      field: "model_reasoning_effort",
+      expected: agent.reasoningEffort,
+      actual: parsed.model_reasoning_effort,
+    });
+  }
+
+  const instructions = parsed.developer_instructions;
+  if (typeof instructions !== "string" || instructions.trim() === "") {
+    throw errorBlock("native_agent_toml_invalid", {
+      agent: agentName,
+      field: "developer_instructions",
+      message: "developer instructions must be non-empty",
+    });
+  }
+
+  for (const expected of [
+    `- role: ${agentName}`,
+    `- posture: ${agent.posture}`,
+    `- model_class: ${agent.modelClass}`,
+    `- routing_role: ${agent.routingRole}`,
+  ]) {
+    if (!instructions.includes(expected)) {
+      throw errorBlock("native_agent_toml_invalid", {
+        agent: agentName,
+        field: "developer_instructions",
+        missing: expected,
+      });
+    }
+  }
+}
+
+export async function verifyNativeAgents(
+  options: VerifyNativeAgentsOptions = {},
+): Promise<VerifyNativeAgentsResult> {
+  const root = resolve(options.root ?? process.cwd());
+  const manifest = options.manifest ?? readCatalogManifest(root);
+  const definitions = options.definitions ?? AGENT_DEFINITIONS;
+  const promptNames = options.promptNames ?? (await readPromptNames(root));
+  const catalogByName = getCatalogAgentByName(manifest);
+  const installableAgentNames = [...getInstallableNativeAgentNames(manifest)].sort();
+
+  assertNativeAgentCanonicalTargets(manifest);
+
+  for (const agent of manifest.agents) {
+    if (!isNativeAgentInstallableStatus(agent.status)) continue;
+    if (!definitions[agent.name]) {
+      throw errorBlock("native_agent_definition_missing", {
+        agent: agent.name,
+        status: agent.status,
+      });
+    }
+    if (!promptNames.has(agent.name)) {
+      throw errorBlock("native_agent_prompt_missing", {
+        agent: agent.name,
+        status: agent.status,
+        path: `prompts/${agent.name}.md`,
+      });
+    }
+  }
+
+  for (const name of Object.keys(definitions).sort()) {
+    if (!catalogByName.has(name)) {
+      throw errorBlock("native_agent_catalog_out_of_sync", {
+        agent: name,
+        message: "agent definition must be listed in catalog agents",
+      });
+    }
+  }
+
+  for (const name of [...promptNames].sort()) {
+    if (catalogByName.has(name)) continue;
+    if (NON_NATIVE_AGENT_PROMPT_ASSETS.has(name)) continue;
+    throw errorBlock("native_agent_prompt_unclassified", {
+      prompt: name,
+      path: `prompts/${name}.md`,
+      message:
+        "prompt files must be cataloged native agents or explicit non-native prompt assets",
+    });
+  }
+
+  for (const name of installableAgentNames) {
+    const agent = definitions[name];
+    if (!agent) continue;
+    const promptPath = join(root, "prompts", `${name}.md`);
+    const promptContent = options.promptNames
+      ? `${name} prompt fixture`
+      : await readFile(promptPath, "utf-8");
+    const toml = generateAgentToml(agent, promptContent);
+    assertTomlStructure(name, agent, toml);
+  }
+
+  const pluginManifest =
+    options.pluginManifest === undefined
+      ? await readPluginManifest(root)
+      : options.pluginManifest;
+  if (pluginManifest) {
+    for (const field of ["agents", "prompts", "hooks"]) {
+      if (pluginManifest[field] !== undefined) {
+        throw errorBlock("native_agent_plugin_boundary_violation", {
+          field,
+          message: "native agents/prompts/hooks are setup-owned, not plugin-scoped",
+        });
+      }
+    }
+  }
+
+  return {
+    installableAgentNames,
+    promptAssetNames: [...promptNames].sort(),
+  };
+}
+
+function parseArgs(argv: string[]): { root: string } {
+  let root = process.cwd();
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--root") {
+      const value = argv[i + 1];
+      if (!value) throw new Error("missing --root value");
+      root = value;
+      i += 1;
+      continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  return { root };
+}
+
+async function main(): Promise<void> {
+  const { root } = parseArgs(process.argv.slice(2));
+  const result = await verifyNativeAgents({ root });
+  console.log(
+    `verified ${result.installableAgentNames.length} installable native agents and ${result.promptAssetNames.length} setup prompt assets`,
+  );
+}
+
+if (process.argv[1]?.endsWith("verify-native-agents.js")) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}