@uluops/setup 0.8.1 → 0.9.1

package/README.md

@@ -19,7 +19,9 @@ npx @uluops/setup
 | Claude Code | Fully supported (default) | `claude` | `~/.claude.json` |
 | OpenCode | Fully supported | `oc` | `~/.config/opencode/opencode.json` |
 | Gemini CLI | Fully supported | `gemini` | `~/.gemini/settings.json` |
-| Codex | Experimental (opt-in via `--harness codex`) | — | `~/.codex/config.toml` |
+| Codex | Fully supported | — | `~/.codex/config.toml` |
+
+> **Codex note:** the TOML writer seeds `approval_mode = "approve"` for every read-side MCP tool exported by `@uluops/ops-mcp` and `@uluops/registry-mcp` so interactive sessions don't surface an approval prompt on every `list_*`/`get_*`/`query_*` call. Write-side tools (`save_run`, `bulk_update_status`, `publish_definition`, etc.) are intentionally NOT pre-approved — Codex still asks before any state-changing operation. A re-install over a hand-tuned config (any `[mcp_servers.<server>.tools.*]` block present) preserves your customizations verbatim and skips the seed step.
 
 ```bash
 # Install for Claude Code (default)
@@ -45,7 +47,7 @@ If you don't pass `--harness` or `--all-detected`, setup probes your home direct
 - **Multiple harnesses detected (non-interactive — `--yes`, `--api-key`, piped stdin)** — to keep CI scripts predictable, this preserves earlier behavior: the first detected harness installs and a dimmed notice lists the others. CI users who want multi-install opt in explicitly with `--all-detected`.
 - **No harnesses detected** — falls back to the default (`claude-code`) so `npx @uluops/setup` always does something useful on a fresh machine.
 
-Passing `--harness <name>` always wins — auto-detection is skipped entirely. Experimental harnesses are excluded from auto-detection (an explicit `--harness` is the only way to opt in).
+Passing `--harness <name>` always wins — auto-detection is skipped entirely. Auto-detection only returns harnesses marked stable; when a future harness ships as experimental, an explicit `--harness <name>` will remain the only way to opt in.
 
 ### Multi-harness install
 
@@ -92,7 +94,7 @@ Each harness gets its own per-section block in the summary:
 | Pipeline commands | 2 | `~/.claude/commands/pipelines/` |
 | Agent metrics hook | 1 | `~/.claude/tools/agent-metrics/` |
 
-> Paths shown are for Claude Code (default). Gemini CLI installs agents as `.md` and commands as `.toml` to `~/.gemini/`. OpenCode installs agents to `~/.config/opencode/agents/`. Agent definitions and commands are transformed to the target harness format at install time from a single source.
+> Paths shown are for Claude Code (default). Gemini CLI installs agents as `.md` and commands as `.toml` to `~/.gemini/`. OpenCode installs agents to `~/.config/opencode/agents/`. Codex installs agents as `.toml` to `~/.codex/agents/` and ships a single `uluops-operator` skill under `~/.codex/skills/` instead of slash commands. Agent definitions and commands are transformed to the target harness format at install time from a single source.
 
 The installer runs these steps in sequence:
 

package/dist/harnesses/codex.js

@@ -11,28 +11,136 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { ULUOPS_SERVERS, } from "./types.js";
 import { atomicWrite } from "../lib/atomic-write.js";
+import { OPS_MCP_SPEC, REGISTRY_MCP_SPEC } from "../lib/mcp-packages.js";
 const RAW_TOML = "__rawToml";
+/**
+ * Tools to seed with `approval_mode = "approve"` (Codex's auto-allow opt-in).
+ *
+ * Seeded ONLY when the user has no prior `[mcp_servers.NAME.tools.*]` blocks
+ * for the server — a re-install over a hand-tuned config preserves the user's
+ * choices verbatim (the merge bails on its own seeds the moment it sees user
+ * intent).
+ *
+ * Only read-side tools are seeded. Writes still prompt — the user retains a
+ * choice point on every state-changing operation. Lists mirror the
+ * `sideEffects: 'read'` declarations in the respective server's tool-registry
+ * (sources of truth: ops-uluops-mcp/src/config/tool-registry.ts and
+ * uluops-registry-mcp/src/config/tool-registry.ts). If a new read tool ships
+ * there, add it here in the same PR — Codex users will silently get a prompt
+ * on first use otherwise.
+ */
+const TRACKER_READ_TOOLS = [
+    "diff_runs",
+    "get_agent_lifecycle",
+    "get_agent_matrix",
+    "get_agent_reliability",
+    "get_agent_runs_analysis",
+    "get_analytics",
+    "get_burndown",
+    "get_discovery",
+    "get_full_taxonomy_analytics",
+    "get_issue_by_fingerprint",
+    "get_issue_details",
+    "get_issue_history",
+    "get_latest_run",
+    "get_project",
+    "get_project_analysis",
+    "get_project_summary",
+    "get_project_trends",
+    "get_run",
+    "get_run_analysis",
+    "get_run_details",
+    "get_taxonomy",
+    "get_velocity",
+    "list_agents",
+    "list_projects",
+    "list_runs",
+    "query_analysis_records",
+    "query_issues",
+    "search_issues",
+    "validate_run",
+];
+const REGISTRY_READ_TOOLS = [
+    "batch_users",
+    "compare_effectiveness",
+    "diff_versions",
+    "get_definition",
+    "get_dependencies",
+    "get_dependents",
+    "get_diff_impact",
+    "get_ecosystem_overview",
+    "get_effectiveness",
+    "get_evolution",
+    "get_execution_stats",
+    "get_fork_lineage",
+    "get_health",
+    "get_language",
+    "get_lineage",
+    "get_model",
+    "get_translation_analytics",
+    "get_translator_version",
+    "get_user",
+    "is_forkable",
+    "list_aliases",
+    "list_definitions",
+    "list_forks",
+    "list_languages",
+    "list_models",
+    "list_providers",
+    "list_versions",
+    "render_definition",
+    "resolve_alias",
+    "search_definitions",
+    "set_default_type",
+    "validate_definition",
+];
 function tomlString(value) {
     return JSON.stringify(value);
 }
-function serverBlock(name, pkg, apiKey) {
+function toolBlock(serverName, toolName) {
     return [
-        `[mcp_servers.${tomlString(name)}]`,
+        `[mcp_servers.${serverName}.tools.${toolName}]`,
+        `approval_mode = "approve"`,
+    ].join("\n");
+}
+function serverBlock(name, pkg, apiKey, seedTools) {
+    const lines = [
+        `[mcp_servers.${name}]`,
         `command = "npx"`,
         `args = ["-y", ${tomlString(pkg)}]`,
         ``,
-        `[mcp_servers.${tomlString(name)}.env]`,
+        `[mcp_servers.${name}.env]`,
         `ULUOPS_API_KEY = ${tomlString(apiKey)}`,
-    ].join("\n");
+    ];
+    for (const tool of seedTools) {
+        lines.push(``, toolBlock(name, tool));
+    }
+    return lines.join("\n");
 }
 function isServerTableFor(name, table) {
     return table === `mcp_servers.${name}` || table === `mcp_servers."${name}"`;
 }
+function isServerEnvTableFor(name, table) {
+    return (table === `mcp_servers.${name}.env` ||
+        table === `mcp_servers."${name}".env`);
+}
 function isServerSubtableFor(name, table) {
     const unquotedPrefix = `mcp_servers.${name}.`;
     const quotedPrefix = `mcp_servers."${name}".`;
     return table.startsWith(unquotedPrefix) || table.startsWith(quotedPrefix);
 }
+function isServerToolTableFor(name, table) {
+    const unquotedPrefix = `mcp_servers.${name}.tools.`;
+    const quotedPrefix = `mcp_servers."${name}".tools.`;
+    return table.startsWith(unquotedPrefix) || table.startsWith(quotedPrefix);
+}
+/**
+ * Strip the main `[mcp_servers.NAME]` and `[mcp_servers.NAME.env]` blocks
+ * but preserve `[mcp_servers.NAME.tools.*]` blocks. Tool overrides may be
+ * user customizations — destroying them on every re-install would punish
+ * anyone who hand-edited their Codex config to deny a specific tool or to
+ * approve one we don't seed.
+ */
 function removeServerConfigBlocks(raw, name) {
     const lines = raw.split("\n");
     const kept = [];
@@ -40,7 +148,7 @@ function removeServerConfigBlocks(raw, name) {
     for (const line of lines) {
         const table = line.trim().match(/^\[([^\]]+)\]$/)?.[1];
         if (table) {
-            skipping = isServerTableFor(name, table) || table === `mcp_servers.${name}.env` || table === `mcp_servers."${name}".env`;
+            skipping = isServerTableFor(name, table) || isServerEnvTableFor(name, table);
         }
         if (!skipping)
             kept.push(line);
@@ -61,6 +169,14 @@ function removeServerSubtree(raw, name) {
     }
     return kept.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
 }
+function hasUserToolEntries(raw, name) {
+    for (const line of raw.split("\n")) {
+        const table = line.trim().match(/^\[([^\]]+)\]$/)?.[1];
+        if (table && isServerToolTableFor(name, table))
+            return true;
+    }
+    return false;
+}
 class CodexMcpConfig {
     async read(path) {
         try {
@@ -72,10 +188,17 @@ class CodexMcpConfig {
     }
     merge(config, apiKey) {
         let raw = typeof config[RAW_TOML] === "string" ? config[RAW_TOML] : "";
+        // Detect prior user customization BEFORE we strip anything. A hand-tuned
+        // config (any `[mcp_servers.NAME.tools.*]` block present) signals user
+        // intent — we replay only main + env, leaving the user's per-tool
+        // approval choices untouched. A fresh config gets the seeded read-tool
+        // approvals so first-launch UX skips the prompt cascade.
+        const trackerHasUserTools = hasUserToolEntries(raw, "uluops-tracker");
+        const registryHasUserTools = hasUserToolEntries(raw, "uluops-registry");
         raw = removeServerConfigBlocks(removeServerConfigBlocks(raw, "uluops-tracker"), "uluops-registry");
         const blocks = [
-            serverBlock("uluops-tracker", "@uluops/ops-mcp", apiKey),
-            serverBlock("uluops-registry", "@uluops/registry-mcp", apiKey),
+            serverBlock("uluops-tracker", OPS_MCP_SPEC, apiKey, trackerHasUserTools ? [] : TRACKER_READ_TOOLS),
+            serverBlock("uluops-registry", REGISTRY_MCP_SPEC, apiKey, registryHasUserTools ? [] : REGISTRY_READ_TOOLS),
         ].join("\n\n");
         return { [RAW_TOML]: [raw.trimEnd(), blocks].filter(Boolean).join("\n\n") + "\n" };
     }
@@ -102,7 +225,7 @@ const home = join(homedir(), ".codex");
 export const codexProfile = {
     name: "codex",
     displayName: "Codex",
-    status: "experimental",
+    status: "stable",
     homeDir: home,
     agentFormat: "toml",
     factoryTarget: "codex",

package/dist/harnesses/opencode.js

@@ -16,6 +16,7 @@ import { join, isAbsolute } from "node:path";
 import { parse as parseJsonc } from "jsonc-parser";
 import { ULUOPS_SERVERS, ConfigParseError } from "./types.js";
 import { atomicWrite } from "../lib/atomic-write.js";
+import { OPS_MCP_SPEC, REGISTRY_MCP_SPEC } from "../lib/mcp-packages.js";
 class OpenCodeMcpConfig {
     /** Maps requested path → actual resolved path (for .jsonc fallback). */
     resolvedPaths = new Map();
@@ -51,7 +52,7 @@ class OpenCodeMcpConfig {
         // their bundled SDKs. See lib/config-merger.ts for rationale.
         const tracker = {
             type: "local",
-            command: ["npx", "-y", "@uluops/ops-mcp"],
+            command: ["npx", "-y", OPS_MCP_SPEC],
             enabled: true,
             timeout: 30000,
             environment: {
@@ -60,7 +61,7 @@ class OpenCodeMcpConfig {
         };
         const registry = {
             type: "local",
-            command: ["npx", "-y", "@uluops/registry-mcp"],
+            command: ["npx", "-y", REGISTRY_MCP_SPEC],
             enabled: true,
             timeout: 30000,
             environment: {

package/dist/harnesses/types.js

@@ -22,9 +22,12 @@ export class HarnessNotTestedError extends Error {
     constructor(harnessName) {
         super(
         // Keep this list in sync with profiles whose `status === "stable"`.
-        // Today: claude-code, opencode, gemini-cli. When a new stable profile
-        // lands, add it here so the error stays actionable.
-        `${harnessName} harness is not yet tested. Use --harness claude-code, --harness opencode, or --harness gemini-cli.`);
+        // Today: claude-code, opencode, gemini-cli, codex. When a new stable
+        // profile lands, add it here so the error stays actionable. (As of
+        // 0.9.0 every shipped profile is stable, so this constructor is
+        // currently unreachable — kept as a structural slot for the next
+        // experimental harness scaffold.)
+        `${harnessName} harness is not yet tested. Use --harness claude-code, --harness opencode, --harness gemini-cli, or --harness codex.`);
         this.name = "HarnessNotTestedError";
     }
 }

package/dist/lib/config-merger.js

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { atomicWrite } from "./atomic-write.js";
-const MCP_PACKAGES = ["@uluops/ops-mcp", "@uluops/registry-mcp"];
+import { MCP_PACKAGES, OPS_MCP_SPEC, REGISTRY_MCP_SPEC, } from "./mcp-packages.js";
 /**
  * In-process memoization for the npm availability probe.
  *
@@ -102,7 +102,7 @@ export function mergeUluopsMcp(config, apiKey, trust = false) {
             ...existing,
             "uluops-tracker": {
                 command: "npx",
-                args: ["-y", "@uluops/ops-mcp"],
+                args: ["-y", OPS_MCP_SPEC],
                 env: {
                     ULUOPS_API_KEY: apiKey,
                 },
@@ -110,7 +110,7 @@ export function mergeUluopsMcp(config, apiKey, trust = false) {
             },
             "uluops-registry": {
                 command: "npx",
-                args: ["-y", "@uluops/registry-mcp"],
+                args: ["-y", REGISTRY_MCP_SPEC],
                 env: {
                     ULUOPS_API_KEY: apiKey,
                 },

package/dist/lib/mcp-packages.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pinned MCP server package versions.
+ *
+ * Every harness's MCP config writer (claude-code/gemini-cli/opencode JSON
+ * mergers, codex TOML writer) stamps these spec strings into the harness
+ * config so `npx -y <spec>` resolves a known-good version instead of
+ * latest. Pinning makes a `@uluops/setup` release self-contained — what
+ * users get on first launch is what the package was tested against,
+ * regardless of when later MCP server versions ship.
+ *
+ * **Bump rule:** when an MCP server publishes a new version, bump the
+ * version here in the same setup release. A pinned setup install never
+ * silently picks up a downstream regression; a missed bump shows up as
+ * the next setup release stamping the previous combination.
+ *
+ * The bare package NAMES (without versions) remain available as
+ * `MCP_PACKAGES` for the npm availability probe — that probe asks
+ * "does this name exist on the registry" not "does this version exist".
+ * Pinning the probe to a specific version would turn a temporary
+ * registry blip on an older version into a setup failure even when
+ * the latest version was reachable.
+ */
+export declare const OPS_MCP_PACKAGE = "@uluops/ops-mcp";
+export declare const OPS_MCP_VERSION = "0.3.1";
+export declare const OPS_MCP_SPEC: "@uluops/ops-mcp@0.3.1";
+export declare const REGISTRY_MCP_PACKAGE = "@uluops/registry-mcp";
+export declare const REGISTRY_MCP_VERSION = "0.2.5";
+export declare const REGISTRY_MCP_SPEC: "@uluops/registry-mcp@0.2.5";
+/**
+ * Bare package names for the npm availability probe. The probe checks
+ * existence on the registry, not version-specific resolvability, so it
+ * uses these unversioned names.
+ */
+export declare const MCP_PACKAGES: readonly string[];

package/dist/lib/mcp-packages.js

@@ -0,0 +1,37 @@
+/**
+ * Pinned MCP server package versions.
+ *
+ * Every harness's MCP config writer (claude-code/gemini-cli/opencode JSON
+ * mergers, codex TOML writer) stamps these spec strings into the harness
+ * config so `npx -y <spec>` resolves a known-good version instead of
+ * latest. Pinning makes a `@uluops/setup` release self-contained — what
+ * users get on first launch is what the package was tested against,
+ * regardless of when later MCP server versions ship.
+ *
+ * **Bump rule:** when an MCP server publishes a new version, bump the
+ * version here in the same setup release. A pinned setup install never
+ * silently picks up a downstream regression; a missed bump shows up as
+ * the next setup release stamping the previous combination.
+ *
+ * The bare package NAMES (without versions) remain available as
+ * `MCP_PACKAGES` for the npm availability probe — that probe asks
+ * "does this name exist on the registry" not "does this version exist".
+ * Pinning the probe to a specific version would turn a temporary
+ * registry blip on an older version into a setup failure even when
+ * the latest version was reachable.
+ */
+export const OPS_MCP_PACKAGE = "@uluops/ops-mcp";
+export const OPS_MCP_VERSION = "0.3.1";
+export const OPS_MCP_SPEC = `${OPS_MCP_PACKAGE}@${OPS_MCP_VERSION}`;
+export const REGISTRY_MCP_PACKAGE = "@uluops/registry-mcp";
+export const REGISTRY_MCP_VERSION = "0.2.5";
+export const REGISTRY_MCP_SPEC = `${REGISTRY_MCP_PACKAGE}@${REGISTRY_MCP_VERSION}`;
+/**
+ * Bare package names for the npm availability probe. The probe checks
+ * existence on the registry, not version-specific resolvability, so it
+ * uses these unversioned names.
+ */
+export const MCP_PACKAGES = [
+    OPS_MCP_PACKAGE,
+    REGISTRY_MCP_PACKAGE,
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uluops/setup",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "description": "Zero-friction installer for UluOps agentic harnesses",
   "license": "MIT",
   "repository": {