@raishin/vanguard-frontier-agentic 2.5.0 → 2.7.0

package/scripts/generate-kiro-powers.mjs

@@ -212,6 +212,239 @@ const PROVIDERS = {
 
 const catalog = JSON.parse(readFileSync(catalogPath, "utf8"));
 
+// --- Dynamic provider discovery and derivation ---
+
+/** Special-case display name mappings for providers not in PROVIDERS. */
+const DISPLAY_NAME_OVERRIDES = {
+  dotnet: ".NET",
+  hr: "HR",
+  fluxcd: "FluxCD",
+  argocd: "ArgoCD",
+  opentelemetry: "OpenTelemetry",
+  "cert-manager": "Cert-Manager",
+  "multi-cloud": "Multi-Cloud",
+};
+
+/** Pre-authored keyword sets for derived providers. */
+const DERIVED_KEYWORDS = {
+  argocd: ["argocd", "gitops", "progressive-delivery", "application-sync"],
+  dotnet: ["dotnet", "csharp", "aspnet-core", "ef-core", "nuget"],
+  marketing: ["marketing-governance", "consent-compliance", "advertising-fairness", "email-authentication"],
+  hr: ["hr-governance", "employment-risk", "compensation-equity", "recruiting"],
+  legal: ["legal-risk", "contract-review", "privacy-compliance", "regulatory"],
+  generic: ["test-quality", "ci-pipeline", "helm-chart", "manifest-review"],
+  "multi-cloud": ["finops", "cloud-pricing", "cost-optimization", "reserved-instances"],
+  backstage: ["backstage", "scaffolder", "software-templates", "developer-portal"],
+  "cert-manager": ["cert-manager", "x509", "certificate-lifecycle", "pki"],
+  cilium: ["cilium", "network-policy", "ebpf", "cluster-mesh"],
+  falco: ["falco", "runtime-threat", "syscall-rules", "container-security"],
+  fluxcd: ["fluxcd", "gitops", "kustomization", "helm-release"],
+  istio: ["istio", "service-mesh", "ambient-mesh", "mtls"],
+  kyverno: ["kyverno", "admission-policy", "cluster-policy", "policy-enforcement"],
+  opentelemetry: ["opentelemetry", "otel-collector", "tracing", "observability-pipeline"],
+  prometheus: ["prometheus", "alertmanager", "metrics-cardinality", "scrape-config"],
+  sigstore: ["sigstore", "cosign", "supply-chain-integrity", "image-signing"],
+};
+
+/**
+ * Discover all unique providers from the catalog where at least one agent
+ * has 'kiro' in its harnesses array.
+ */
+function discoverKiroProviders() {
+  const providers = new Set();
+  for (const entry of catalog) {
+    if (
+      entry.type === "agent" &&
+      Array.isArray(entry.harnesses) &&
+      entry.harnesses.includes("kiro")
+    ) {
+      providers.add(entry.provider);
+    }
+  }
+  return [...providers].sort();
+}
+
+/**
+ * Title-case a provider name, handling special cases.
+ */
+function titleCaseProvider(provider) {
+  if (DISPLAY_NAME_OVERRIDES[provider]) return DISPLAY_NAME_OVERRIDES[provider];
+  return provider
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("-");
+}
+
+/**
+ * Derive a topic summary from agent IDs for description generation.
+ */
+function deriveTopics(entries) {
+  const topics = entries
+    .map((e) => e.id)
+    .filter((id) => !id.endsWith("-maestro-agent"))
+    .map((id) => {
+      // Strip provider prefix and -agent / -review-agent suffix
+      let topic = id
+        .replace(/-review-agent$/, "")
+        .replace(/-agent$/, "")
+        .replace(/-run-agent$/, "");
+      // Remove known provider prefixes
+      const prefixes = [
+        "dotnet-", "hr-", "legal-", "marketing-", "finops-",
+        "argocd-", "backstage-", "cert-manager-", "cilium-",
+        "falco-", "fluxcd-", "istio-", "kyverno-",
+        "opentelemetry-", "prometheus-", "sigstore-",
+      ];
+      for (const pfx of prefixes) {
+        if (topic.startsWith(pfx)) {
+          topic = topic.slice(pfx.length);
+          break;
+        }
+      }
+      return topic.replace(/-/g, " ");
+    })
+    .slice(0, 4);
+  return topics.join(", ");
+}
+
+/**
+ * Auto-generate steering content for a provider NOT in the hardcoded
+ * PROVIDERS object.
+ */
+function deriveProviderConfig(provider, catalogEntries) {
+  const displayLabel = titleCaseProvider(provider);
+  const displayName = `Vanguard Frontier \u2014 ${displayLabel}`;
+
+  const entries = catalogEntries.filter(
+    (e) => e.type === "agent" && e.provider === provider,
+  );
+  const maestro = entries.find((e) => e.id.endsWith("-maestro-agent"));
+  const liveGuards = entries.filter((e) => /-live-/.test(e.id));
+
+  // Build description (max 3 sentences)
+  let description;
+  if (maestro && entries.length > 2) {
+    const topics = deriveTopics(entries);
+    description = `Curated ${displayLabel} agents for ${topics}. Routes via ${maestro.id} to specialist agents based on task scope. Static review only; no live mutations.`;
+  } else if (entries.length === 1) {
+    // Single agent, no maestro
+    const summary = entries[0].summary || "";
+    // Split into sentences - skip "Agent for <id>." prefix if present
+    const sentences = summary.split(/(?<=[.!?])\s/);
+    let useSentence = sentences[0] || "";
+    if (/^Agent for\s/i.test(useSentence) && sentences.length > 1) {
+      useSentence = sentences[1];
+    }
+    // Remove trailing period for reassembly
+    useSentence = useSentence.replace(/\.$/, "");
+    // Strip leading "Static review of" / "Review" prefix to avoid doubling
+    let core = useSentence
+      .replace(/^Static,?\s+evidence-gated\s+review\s+of\s+/i, "")
+      .replace(/^Static\s+review\s+of\s+/i, "")
+      .replace(/^Review\s+(a\s+)?/i, "");
+    // Truncate if too long, respecting word boundaries
+    if (core.length > 120) {
+      const truncated = core.substring(0, 117);
+      const lastSpace = truncated.lastIndexOf(" ");
+      core = (lastSpace > 0 ? truncated.substring(0, lastSpace) : truncated) + "...";
+    }
+    const sep = core.endsWith("...") ? " " : ". ";
+    description = `Reviews ${core.charAt(0).toLowerCase() + core.slice(1)}${sep}Static review only; no live mutations.`;
+  } else {
+    // Multiple agents, no maestro
+    const topics = deriveTopics(entries);
+    description = `Curated ${displayLabel} review agents covering ${topics}. Reference agents directly under agents/${provider}/. Static review only; no live mutations.`;
+  }
+
+  // Keywords
+  const keywords = DERIVED_KEYWORDS[provider] || [
+    provider,
+    "static-review",
+    "configuration-audit",
+    "best-practices",
+  ];
+
+  // Invariants
+  const invariants = [];
+  if (liveGuards.length > 0) {
+    invariants.push(
+      `Live-guard agents (${provider}-live-*) must never be auto-dispatched; require explicit approval and rollback plan.`,
+    );
+  }
+  if (maestro) {
+    invariants.push(
+      `Route all tasks through ${maestro.id} for proper classification and dispatch.`,
+    );
+  }
+  invariants.push(
+    "Static review only -- agents analyze configuration and provide findings without mutating live systems.",
+  );
+  // Add domain-specific invariants
+  if (provider === "dotnet") {
+    invariants.push("Review covers language runtime, frameworks, data access, testing, and supply-chain integrity.");
+  } else if (provider === "hr") {
+    invariants.push("All findings must respect employee privacy and data-minimization principles.");
+  } else if (provider === "legal") {
+    invariants.push("Agents provide risk-flagging only; output is not legal advice and does not create attorney-client privilege.");
+  } else if (provider === "marketing") {
+    invariants.push("Review covers consent, privacy, fairness, and regulatory compliance for marketing systems.");
+  } else if (provider === "multi-cloud") {
+    invariants.push("Cost recommendations are estimates based on public pricing; verify against actual billing before acting.");
+  } else if (provider === "generic") {
+    invariants.push("Agents are provider-agnostic and focus on CI, Helm, manifest, and test-quality patterns.");
+  } else if (provider === "argocd") {
+    invariants.push("Sync and rollout strategies must be validated against the target cluster GitOps workflow.");
+  } else if (provider === "backstage") {
+    invariants.push("Template parameters and scaffolder actions must be reviewed for injection and secret-exposure risks.");
+  } else if (provider === "cert-manager") {
+    invariants.push("Certificate renewal windows and issuer trust chains must be validated before any policy change.");
+  } else if (provider === "cilium") {
+    invariants.push("Network policies must be reviewed for unintended traffic blocking across namespaces and cluster-mesh endpoints.");
+  } else if (provider === "falco") {
+    invariants.push("Rule changes must be evaluated for false-positive rate impact on production alerting.");
+  } else if (provider === "fluxcd") {
+    invariants.push("Kustomization and HelmRelease reconciliation intervals must align with the GitOps change cadence.");
+  } else if (provider === "istio") {
+    invariants.push("Service mesh policies affect traffic routing cluster-wide; review blast radius before changes.");
+  } else if (provider === "kyverno") {
+    invariants.push("Cluster-scoped policies can reject legitimate workloads; validate against existing deployments before applying.");
+  } else if (provider === "opentelemetry") {
+    invariants.push("Collector pipeline changes affect observability for all instrumented services; review cardinality impact.");
+  } else if (provider === "prometheus") {
+    invariants.push("Alerting rule and scrape config changes affect monitoring coverage; review for metric-name collisions.");
+  } else if (provider === "sigstore") {
+    invariants.push("Supply-chain policy changes can block valid deployments; verify cosign keyless trust roots before enforcement.");
+  }
+
+  return { displayName, description, keywords, invariants };
+}
+
+/**
+ * Build a merged map combining hand-authored PROVIDERS with auto-derived
+ * entries for all kiro-enabled providers in the catalog.
+ */
+function buildMergedProviders() {
+  const kiroProviders = discoverKiroProviders();
+  const merged = {};
+
+  for (const provider of kiroProviders) {
+    if (PROVIDERS[provider]) {
+      merged[provider] = PROVIDERS[provider];
+    } else {
+      merged[provider] = deriveProviderConfig(provider, catalog);
+    }
+  }
+
+  // Sort alphabetically for deterministic output
+  const sorted = {};
+  for (const key of Object.keys(merged).sort()) {
+    sorted[key] = merged[key];
+  }
+  return sorted;
+}
+
+const allProviders = buildMergedProviders();
+
 function summarize(provider) {
   const entries = catalog.filter(
     (e) => e.type === "agent" && e.provider === provider,
@@ -254,7 +487,9 @@ function renderPower(provider, cfg) {
 
   const adapterNote =
     kiroAvailable === total
-      ? `All ${total} agents in this provider ship a Kiro adapter (\`harnesses/kiro-ide.agent.md\`, \`kiro-cli.agent.json\`).`
+      ? total === 1
+        ? `The single agent in this provider ships a Kiro adapter (\`harnesses/kiro-ide.agent.md\`, \`kiro-cli.agent.json\`).`
+        : `All ${total} agents in this provider ship a Kiro adapter (\`harnesses/kiro-ide.agent.md\`, \`kiro-cli.agent.json\`).`
       : kiroAvailable === 0
         ? `This provider's ${total} agents do not yet ship Kiro adapters — this Power supplies steering content only. Use \`npx vfa-export-agents --platform kiro --provider ${provider}\` from the npm package once Kiro adapters land.`
         : `${kiroAvailable} of ${total} agents in this provider ship a Kiro adapter; the rest provide steering context only.`;
@@ -273,7 +508,9 @@ function renderPower(provider, cfg) {
     "",
     maestroLine,
     "",
-    "Use the maestro as the entry point: classify the task, then dispatch to one specialist or a parallel team of specialists. Never have the maestro itself execute a live mutation.",
+    maestro
+      ? "Use the maestro as the entry point: classify the task, then dispatch to one specialist or a parallel team of specialists. Never have the maestro itself execute a live mutation."
+      : "Reference agents directly from agents/" + provider + "/ without maestro-based routing.",
     "",
     "## Live-guard agents (gate_mode only)",
     "",
@@ -299,10 +536,114 @@ function renderPower(provider, cfg) {
   return frontmatter + body;
 }
 
+function renderReadme() {
+  const providerKeys = Object.keys(allProviders);
+  const count = providerKeys.length;
+  const tree = providerKeys
+    .map((p, i) => {
+      const prefix = i < count - 1 ? "├──" : "└──";
+      return `${prefix} vanguard-${p}/POWER.md`;
+    })
+    .join("\n");
+
+  return `# \`powers/\` — Kiro Powers
+
+This directory holds **${count} Kiro Powers** for \`vanguard-frontier-agentic\`, one
+per cloud/platform/IaC provider. Each Power is a directory containing a
+\`POWER.md\` file with strict-5 frontmatter and steering content.
+
+## What's in here
+
+\`\`\`
+powers/
+${tree}
+\`\`\`
+
+Each \`POWER.md\` declares:
+
+- **Frontmatter (strict-5):** \`name\`, \`displayName\`, \`description\` (≤ 3
+  sentences), \`keywords\` (specific, non-broad), \`author\`. **No other fields
+  permitted** by Kiro spec.
+- **Body steering:** when to engage, routing pattern (\`<provider>-maestro\`),
+  live-mutation discipline, provider-specific invariants (e.g. MLPS 2.0 for
+  Alibaba/Huawei, Enterprise Project vs IAM scope for Huawei, account-ID
+  /region confirmation for AWS).
+
+## How users install
+
+Kiro Powers don't have a one-command marketplace install — the Powers panel
+is per-Power directory add. Users clone the repo and add each Power they
+need via the Kiro UI:
+
+\`\`\`bash
+# 1. Clone the repo
+git clone https://github.com/Raishin/vanguard-frontier-agentic
+cd vanguard-frontier-agentic
+\`\`\`
+
+\`\`\`text
+2. In Kiro:
+   Open the Powers panel → "Add Custom Power" → "Local Directory"
+   Paste the absolute path to the Power(s) you need:
+      /absolute/path/to/vanguard-frontier-agentic/powers/vanguard-aws
+      /absolute/path/to/vanguard-frontier-agentic/powers/vanguard-kubernetes
+   Repeat for each provider you work with.
+\`\`\`
+
+## How to update
+
+\`\`\`bash
+# Regenerate the ${count} Powers from catalog/agents.json + per-provider config:
+npm run kiro-powers:write
+
+# Then verify everything is in sync:
+npm run validate:kiro-powers
+\`\`\`
+
+The \`validate\` chain runs \`validate:kiro-powers\` automatically. The
+validator enforces:
+
+- strict-5 frontmatter (any extra field fails)
+- lowercase kebab-case names
+- name matches directory name
+- description ≤ 3 sentences (decimal-aware — "MLPS 2.0" doesn't count as a
+  sentence break)
+- non-empty keywords list, no broad terms (\`cloud\`, \`devops\`, \`code\`,
+  \`agent\`, \`ml\`, etc.) per Kiro's anti-false-activation guidance
+- generator in sync (\`--check\`)
+
+## Schema references (official Kiro docs)
+
+- **Kiro Powers repo:** <https://github.com/kirodotdev/powers>
+- **POWER.md frontmatter spec:**
+  <https://github.com/kirodotdev/powers/blob/main/power-builder/POWER.md>
+- **Interactive power builder:**
+  <https://github.com/kirodotdev/powers/blob/main/power-builder/steering/interactive.md>
+- **Testing a power locally:**
+  <https://github.com/kirodotdev/powers/blob/main/power-builder/steering/testing.md>
+- **Kiro IDE:** <https://kiro.dev/>
+
+## Design notes
+
+- **One Power per provider, not one mega-Power** — Kiro docs warn that
+  broad keywords trigger false activations across unrelated tasks. One
+  narrowly-scoped Power per provider keeps activation precise:
+  \`vanguard-alibaba\` activates on Alibaba Cloud work only; \`vanguard-aws\`
+  never activates on Azure questions.
+- **Hetzner and Contabo Powers exist** even though their agents don't yet
+  ship Kiro adapter files (their \`harnesses: [codex, claude-code]\`). Powers
+  are steering-first — the steering content stands alone. When their Kiro
+  adapter files land, the Powers will gain agent-routing as well.
+- **No \`version\`, \`repository\`, \`license\`, or \`tags\`** — Kiro spec
+  explicitly forbids these fields in frontmatter. The validator fails on
+  any extra field.
+`;
+}
+
 const errors = [];
 const written = [];
 
-for (const [provider, cfg] of Object.entries(PROVIDERS)) {
+for (const [provider, cfg] of Object.entries(allProviders)) {
   const dir = join(powersRoot, `vanguard-${provider}`);
   const file = join(dir, "POWER.md");
   const next = renderPower(provider, cfg);
@@ -322,15 +663,29 @@ for (const [provider, cfg] of Object.entries(PROVIDERS)) {
   }
 }
 
+// Generate/check README.md
+const readmePath = join(powersRoot, "README.md");
+const nextReadme = renderReadme();
+if (check) {
+  if (!existsSync(readmePath)) {
+    errors.push(`${relative(repoRoot, readmePath)} is missing`);
+  } else if (readFileSync(readmePath, "utf8") !== nextReadme) {
+    errors.push(`${relative(repoRoot, readmePath)} is stale; run npm run kiro-powers:write`);
+  }
+} else {
+  writeFileSync(readmePath, nextReadme);
+  written.push(relative(repoRoot, readmePath));
+}
+
 if (check) {
   if (errors.length) {
     errors.forEach((e) => console.error(`ERROR: ${e}`));
     process.exit(1);
   }
   console.log(
-    `OK: ${Object.keys(PROVIDERS).length} Kiro Powers are in sync`,
+    `OK: ${Object.keys(allProviders).length} Kiro Powers are in sync`,
   );
 } else {
-  console.log(`OK: wrote ${written.length} Kiro Powers`);
+  console.log(`OK: wrote ${written.length} Kiro Powers (+ README.md)`);
   written.forEach((f) => console.log(`  ${f}`));
 }

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");