@raishin/vanguard-frontier-agentic 2.5.0 → 2.6.0

package/scripts/install-codex-home.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * Reliable two-stage installer for Vanguard Frontier Agentic on Codex.
+ *
+ * Stage 1: register/refresh the Codex plugin marketplace.
+ * Stage 2: export all Codex-capable agents and companion skills into a Codex home.
+ */
+
+import { spawnSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const exporter = path.join(repoRoot, "scripts", "export-marketplace-agents.mjs");
+
+const args = process.argv.slice(2);
+const opts = {
+  marketplace: "Raishin/vanguard-frontier-agentic",
+  repo: os.homedir(),
+  force: true,
+  skipMarketplace: false,
+  dryRun: false,
+};
+
+function usage(exitCode = 0) {
+  const out = exitCode === 0 ? console.log : console.error;
+  out(`Usage: node scripts/install-codex-home.mjs [options]\n\nOptions:\n  --marketplace <source>   Codex marketplace source (default: Raishin/vanguard-frontier-agentic)\n  --repo <path>            Target home/repo path whose .codex folder receives agents/skills (default: $HOME)\n  --dry-run                Do not write agents/skills; pass --dry-run to exporter\n  --skip-marketplace       Skip codex plugin marketplace add/upgrade\n  --no-force               Do not pass --force to exporter\n  -h, --help               Show this help\n`);
+  process.exit(exitCode);
+}
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === "-h" || arg === "--help") usage(0);
+  if (arg === "--marketplace") {
+    const val = args[++i];
+    if (!val || val.startsWith("-")) { console.error("--marketplace requires a non-flag value"); usage(1); }
+    opts.marketplace = val;
+  } else if (arg === "--repo") {
+    const val = args[++i];
+    if (!val || val.startsWith("-")) { console.error("--repo requires a non-flag value"); usage(1); }
+    opts.repo = val;
+  }
+  else if (arg === "--dry-run") opts.dryRun = true;
+  else if (arg === "--skip-marketplace") opts.skipMarketplace = true;
+  else if (arg === "--no-force") opts.force = false;
+  else {
+    console.error(`Unknown option: ${arg}`);
+    usage(1);
+  }
+}
+
+if (!opts.marketplace) {
+  console.error("--marketplace cannot be empty");
+  process.exit(1);
+}
+if (!opts.repo) {
+  console.error("--repo cannot be empty");
+  process.exit(1);
+}
+
+function run(label, command, commandArgs, options = {}) {
+  console.error(`\n[${label}] ${command} ${commandArgs.join(" ")}`);
+  const result = spawnSync(command, commandArgs, {
+    cwd: repoRoot,
+    stdio: "inherit",
+    ...options,
+  });
+  if (result.error) {
+    console.error(`[${label}] failed to start: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (result.status !== 0) {
+    console.error(`[${label}] exited ${result.status}`);
+    process.exit(result.status ?? 1);
+  }
+}
+
+if (!opts.skipMarketplace) {
+  run("marketplace-add", "codex", ["plugin", "marketplace", "add", opts.marketplace]);
+  const marketplaceName = opts.marketplace
+    .split("/").pop()
+    ?.replace(/\.git$/, "")
+    ?.replace(/@.+$/, "");
+  if (marketplaceName) {
+    run("marketplace-upgrade", "codex", ["plugin", "marketplace", "upgrade", marketplaceName]);
+  }
+}
+
+const exportArgs = ["--platform", "codex", "--all", "--repo", opts.repo];
+if (opts.force) exportArgs.push("--force");
+if (opts.dryRun) exportArgs.push("--dry-run");
+run("export-agents-and-skills", process.execPath, [exporter, ...exportArgs]);
+
+console.error("\nOK: two-stage Codex install completed");

package/tests/test-codex-plugin-marketplace-install.test.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Optional E2E check for the real Codex marketplace-add command.
+ *
+ * This test is intentionally opt-in because it runs the installed `codex` CLI
+ * and may hit the network when CODEX_PLUGIN_MARKETPLACE_SOURCE is a GitHub
+ * shorthand. It uses an isolated CODEX_HOME and never writes to ~/.codex.
+ *
+ * What it proves:
+ *   - `codex plugin marketplace add <source>` exits successfully.
+ *   - Codex tracks the marketplace in the isolated CODEX_HOME/config.toml.
+ *   - Codex materializes the marketplace source under CODEX_HOME/.tmp/marketplaces.
+ *   - The materialized marketplace contains the repo's Codex marketplace and plugin manifests.
+ *
+ * What it does NOT prove:
+ *   - It does not prove a plugin was installed into CODEX_HOME/plugins/cache/... .
+ *     OpenAI docs describe that as plugin installation through a marketplace;
+ *     the current CLI command under test is marketplace-add, not plugin-install.
+ *
+ * Run:
+ *   RUN_CODEX_PLUGIN_MARKETPLACE_E2E=1 node tests/test-codex-plugin-marketplace-install.test.mjs
+ *
+ * Optional override:
+ *   CODEX_PLUGIN_MARKETPLACE_SOURCE=Raishin/vanguard-frontier-agentic@main \
+ *   RUN_CODEX_PLUGIN_MARKETPLACE_E2E=1 node tests/test-codex-plugin-marketplace-install.test.mjs
+ *
+ * Strict cache assertion, expected to fail for marketplace-add-only on the
+ * current Codex CLI unless a separate plugin install path populates cache:
+ *   EXPECT_CODEX_PLUGIN_CACHE=1 RUN_CODEX_PLUGIN_MARKETPLACE_E2E=1 \
+ *   node tests/test-codex-plugin-marketplace-install.test.mjs
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const enabled = process.env.RUN_CODEX_PLUGIN_MARKETPLACE_E2E === "1";
+if (!enabled) {
+  console.log("SKIP codex marketplace E2E; set RUN_CODEX_PLUGIN_MARKETPLACE_E2E=1 to run it");
+  process.exit(0);
+}
+
+const source = process.env.CODEX_PLUGIN_MARKETPLACE_SOURCE || "Raishin/vanguard-frontier-agentic";
+const marketplaceName = process.env.CODEX_PLUGIN_MARKETPLACE_NAME || "vanguard-frontier-agentic";
+const expectPluginCache = process.env.EXPECT_CODEX_PLUGIN_CACHE === "1";
+const codexHome = fs.mkdtempSync(path.join(os.tmpdir(), "vfa-codex-home-"));
+
+let failures = 0;
+const ok = (msg) => console.log(`OK   ${msg}`);
+const fail = (msg) => {
+  console.log(`FAIL ${msg}`);
+  failures += 1;
+};
+
+function exists(rel) {
+  return fs.existsSync(path.join(codexHome, rel));
+}
+
+try {
+  const result = spawnSync(
+    "codex",
+    ["plugin", "marketplace", "add", source],
+    {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        CODEX_HOME: codexHome,
+      },
+      timeout: 120000,
+    },
+  );
+
+  if (result.error?.code === "ENOENT") {
+    console.log("SKIP codex marketplace E2E; `codex` executable not found on PATH");
+    process.exit(0);
+  }
+  if (result.signal === "SIGTERM") {
+    fail("codex marketplace add timed out after 120s");
+  }
+  if (result.status === 0) {
+    ok(`codex plugin marketplace add ${source} exits 0`);
+  } else {
+    fail(`codex marketplace add exited ${result.status}; stderr=${(result.stderr || "").slice(0, 1000)}`);
+  }
+
+  const configPath = path.join(codexHome, "config.toml");
+  const config = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "";
+  if (config.includes(`[marketplaces.${marketplaceName}]`)) {
+    ok(`config.toml tracks marketplace ${marketplaceName}`);
+  } else {
+    fail(`config.toml missing [marketplaces.${marketplaceName}]`);
+  }
+
+  const installedRoot = path.join(codexHome, ".tmp", "marketplaces", marketplaceName);
+  if (fs.existsSync(installedRoot)) {
+    ok(`marketplace source materialized at ${installedRoot}`);
+  } else {
+    fail(`marketplace source missing at ${installedRoot}`);
+  }
+
+  const requiredFiles = [
+    `.tmp/marketplaces/${marketplaceName}/.agents/plugins/marketplace.json`,
+    `.tmp/marketplaces/${marketplaceName}/plugins/vanguard-frontier-agentic/.codex-plugin/plugin.json`,
+    `.tmp/marketplaces/${marketplaceName}/plugins/cross-platform-agent-template/.codex-plugin/plugin.json`,
+  ];
+  for (const rel of requiredFiles) {
+    if (exists(rel)) ok(`${rel} exists`);
+    else fail(`${rel} missing`);
+  }
+
+  const cacheRoot = path.join(codexHome, "plugins", "cache", marketplaceName);
+  if (fs.existsSync(cacheRoot)) {
+    ok(`plugin cache exists at ${cacheRoot}`);
+  } else if (expectPluginCache) {
+    fail(`plugin cache missing at ${cacheRoot}`);
+  } else {
+    console.log(`INFO plugin cache not created by marketplace-add alone: ${cacheRoot}`);
+  }
+} finally {
+  if (process.env.KEEP_CODEX_MARKETPLACE_E2E_HOME !== "1") {
+    fs.rmSync(codexHome, { recursive: true, force: true });
+  } else {
+    console.log(`INFO kept isolated CODEX_HOME at ${codexHome}`);
+  }
+}
+
+if (failures > 0) {
+  console.error(`\n${failures} check(s) failed`);
+  process.exit(1);
+}
+console.log("\nOK: codex marketplace add E2E checks passed");

package/tests/test-vfa-export-coverage.test.mjs

@@ -35,6 +35,8 @@
  *     16. --dry-run --no-skills omits skill lines.
  *     17. cursor --dry-run emits agent lines but no skill lines (unsupported platform).
  *     18. --dry-run stderr summary reports skill count on skill-capable platform.
+ *     19. codex --all --dry-run emits both agent and skill lines.
+ *     20. codex --dry-run --no-skills omits skill lines.
  *
  *   F. Full CLI flag surface
  *     19. --list exits 0 and prints all agents.
@@ -46,6 +48,8 @@
  *     25. --platform claude (alias) resolves to claude-code.
  *     26. --no-skills writes agent file but no skills directory.
  *     27. --force overwrites existing agent files without error.
+ *     28. codex export writes agent + companion skill and rewrites skill path.
+ *     29. two-stage Codex installer dry-run plans all agents and skills.
  *
  *   G. Error / rejection cases
  *     28. No args → usage text printed, non-zero exit.
@@ -65,6 +69,7 @@ import { fileURLToPath } from "node:url";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const exporter = path.join(repoRoot, "scripts", "export-marketplace-agents.mjs");
+const installer = path.join(repoRoot, "scripts", "install-codex-home.mjs");
 
 const agents = JSON.parse(fs.readFileSync(path.join(repoRoot, "catalog/agents.json"), "utf8"));
 const skills = JSON.parse(fs.readFileSync(path.join(repoRoot, "catalog/skills.json"), "utf8"));
@@ -133,6 +138,12 @@ function run(args) {
   return { stdout: r.stdout ?? "", stderr: r.stderr ?? "", exitCode: r.status ?? 0 };
 }
 
+function runInstaller(args) {
+  const r = spawnSync(process.execPath, [installer, ...args], { encoding: "utf8", timeout: 30000 });
+  if (r.signal === "SIGTERM") fail(`installer timed out (30s) for: ${args.join(" ")}`);
+  return { stdout: r.stdout ?? "", stderr: r.stderr ?? "", exitCode: r.status ?? 0 };
+}
+
 // 5. --provider <p> --all should list the same count as the catalog says.
 {
   const r = run(["--platform", "claude-code", "--provider", "nvidia", "--all", "--dry-run"]);
@@ -518,6 +529,31 @@ function findLeakedSkills(skillNames, expectedProvider) {
   }
 }
 
+// E19: codex --all --dry-run emits both agents and companion skills.
+{
+  const r = run(["--platform", "codex", "--all", "--dry-run"]);
+  const agentCount = (r.stdout.match(/^export agent:/gm) || []).length;
+  const skillCount = (r.stdout.match(/^export skill:/gm) || []).length;
+  const codexAgents = agents.filter((a) => Array.isArray(a.harnesses) && a.harnesses.includes("codex"));
+  if (r.exitCode === 0 && agentCount === codexAgents.length && skillCount === skills.length && /\d+ skill\(s\)/.test(r.stderr)) {
+    ok(`E19 codex --all --dry-run emits agents (${agentCount}) and skills (${skillCount})`);
+  } else {
+    fail(`E19 codex dry-run expected ${codexAgents.length} agents and ${skills.length} skills, got agents=${agentCount} skills=${skillCount}; exit=${r.exitCode}; stderr=${r.stderr.slice(0, 300)}`);
+  }
+}
+
+// E20: codex --dry-run --no-skills emits agent lines but no skill lines.
+{
+  const r = run(["--platform", "codex", "--agents", "aws-iam-least-privilege-review-agent", "--dry-run", "--no-skills"]);
+  const agentCount = (r.stdout.match(/^export agent:/gm) || []).length;
+  const skillCount = (r.stdout.match(/^export skill:/gm) || []).length;
+  if (r.exitCode === 0 && agentCount === 1 && skillCount === 0) {
+    ok("E20 codex --dry-run --no-skills: 1 agent line, 0 skill lines");
+  } else {
+    fail(`E20 expected 1 agent and 0 skills, got agents=${agentCount} skills=${skillCount}; exit=${r.exitCode}`);
+  }
+}
+
 // ── F. Full CLI flag surface ──────────────────────────────────────────────────
 
 // F19: --list exits 0 and emits one line per agent.
@@ -638,6 +674,78 @@ function findLeakedSkills(skillNames, expectedProvider) {
   }
 }
 
+// F28: codex real write installs agent + companion skill and rewrites skill path.
+{
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "vfa-test-codex-skills-"));
+  try {
+    const r = run(["--platform", "codex", "--agents", "aws-iam-least-privilege-review-agent", "--repo", tmpDir]);
+    const agentFile = path.join(tmpDir, ".codex", "agents", "aws-iam-least-privilege-review-agent.toml");
+    const skillDir = path.join(tmpDir, ".codex", "skills", "aws-iam-least-privilege-review");
+    const skillFile = path.join(skillDir, "SKILL.md");
+    const agentText = fs.existsSync(agentFile) ? fs.readFileSync(agentFile, "utf8") : "";
+    const expectedPathLine = `path = ${JSON.stringify(skillDir)}`;
+    if (
+      r.exitCode === 0 &&
+      fs.existsSync(agentFile) &&
+      fs.existsSync(skillFile) &&
+      agentText.includes(expectedPathLine) &&
+      !agentText.includes('path = "skills/aws/aws-iam-least-privilege-review/SKILL.md"')
+    ) {
+      ok("F28 codex export writes agent + skill and rewrites skill path to installed folder");
+    } else {
+      fail(`F28 codex export invalid: exit=${r.exitCode} agent=${fs.existsSync(agentFile)} skill=${fs.existsSync(skillFile)} hasExpectedPath=${agentText.includes(expectedPathLine)} stderr=${r.stderr.slice(0, 300)}`);
+    }
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// F28b: skill bundling refuses destination symlinks even with --force.
+{
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "vfa-test-skill-symlink-"));
+  const outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), "vfa-test-outside-"));
+  const outsideFile = path.join(outsideDir, "OUTSIDE_SENTINEL");
+  try {
+    const skillDir = path.join(tmpDir, ".codex", "skills", "aws-iam-least-privilege-review");
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(outsideFile, "ORIGINAL_OUTSIDE_SENTINEL\n");
+    fs.symlinkSync(outsideFile, path.join(skillDir, "SKILL.md"));
+    const r = run([
+      "--platform", "codex",
+      "--agents", "aws-iam-least-privilege-review-agent",
+      "--repo", tmpDir,
+      "--force",
+    ]);
+    const outsideText = fs.readFileSync(outsideFile, "utf8");
+    if (r.exitCode !== 0 && /symbolic link destination in skill tree/i.test(r.stderr) && outsideText === "ORIGINAL_OUTSIDE_SENTINEL\n") {
+      ok("F28b codex skill export rejects destination symlink and preserves outside file");
+    } else {
+      fail(`F28b expected symlink rejection without outside overwrite; exit=${r.exitCode} preserved=${outsideText === "ORIGINAL_OUTSIDE_SENTINEL\n"} stderr=${r.stderr.slice(0, 300)}`);
+    }
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(outsideDir, { recursive: true, force: true });
+  }
+}
+
+// F29: two-stage installer dry-run composes marketplace-safe export path.
+{
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "vfa-test-two-stage-"));
+  try {
+    const r = runInstaller(["--dry-run", "--skip-marketplace", "--repo", tmpDir]);
+    const combined = `${r.stdout}
+${r.stderr}`;
+    const planMatch = /(\d+) agent\(s\), (\d+) skill\(s\) planned/.exec(combined);
+    if (r.exitCode === 0 && planMatch && parseInt(planMatch[1], 10) > 0 && parseInt(planMatch[2], 10) > 0) {
+      ok(`F29 two-stage Codex installer dry-run plans all agents and skills (${planMatch[1]} agents, ${planMatch[2]} skills)`);
+    } else {
+      fail(`F29 installer dry-run did not plan expected agents/skills; exit=${r.exitCode} output=${combined.slice(-500)}`);
+    }
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
 // ── G. Error / rejection cases ────────────────────────────────────────────────
 
 // G28: No args → usage text printed to stderr, non-zero exit.

package/tests/validate-codex-marketplace.py

@@ -116,12 +116,34 @@ def main() -> int:
                 f"{prefix} ({name}): plugin.json name {manifest.get('name')!r} must equal marketplace entry name {name!r}",
             )
 
-        # Version parity for the primary plugin
+        # Version parity and install-surface checks for the primary plugin.
         if name == "vanguard-frontier-agentic":
             if manifest.get("version") != pkg.get("version"):
                 errors.append(
                     f"{prefix} ({name}): plugin.json version {manifest.get('version')!r} != package.json {pkg.get('version')!r}",
                 )
+            if manifest.get("skills") != "./skills/":
+                errors.append(
+                    f"{prefix} ({name}): plugin.json must declare skills './skills/' for the bundled Codex install skill",
+                )
+            install_skill = plugin_dir / "skills" / "vanguard-frontier-agentic-install" / "SKILL.md"
+            if not install_skill.is_file():
+                errors.append(
+                    f"{prefix} ({name}): bundled install skill is missing at {install_skill.relative_to(REPO)}",
+                )
+
+        skills_path = manifest.get("skills")
+        if skills_path is not None:
+            if not isinstance(skills_path, str) or not skills_path.startswith("./"):
+                errors.append(f"{prefix} ({name}): plugin.json skills path must be a './'-prefixed string")
+            else:
+                skills_dir = (plugin_dir / skills_path).resolve()
+                if not skills_dir.is_relative_to(plugin_dir.resolve()):
+                    errors.append(f"{prefix} ({name}): plugin.json skills path must stay inside plugin root")
+                elif not skills_dir.is_dir():
+                    errors.append(f"{prefix} ({name}): plugin.json skills directory {skills_path!r} is missing")
+                elif not any(skills_dir.glob("*/SKILL.md")):
+                    errors.append(f"{prefix} ({name}): plugin.json skills directory has no */SKILL.md entries")
 
         policy = plugin.get("policy") or {}
         install = policy.get("installation")