xcodebug 1.2.3 → 1.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/GUIDE.md CHANGED
@@ -12,10 +12,21 @@ Enter these commands in the client's chat input. A bare `/xcodebug` (`$xcodebug`
12
12
  in Codex) builds as needed, installs, launches and starts capturing with defaults.
13
13
  Use `/xcodebug status` (`$xcodebug status` in Codex) to inspect current captures.
14
14
 
15
- After installing the MCP server, run `xcodebug-setup-codex` once to register
16
- the server when missing and set Codex's 4200-second tool timeout. From a
17
- checkout, use `node bin/xcodebug-setup-codex.mjs`. This explicit command keeps
18
- package installation from changing Codex configuration silently.
15
+ After installing the MCP server, run `xcodebug-setup-codex` once. It registers
16
+ the server when missing, adds the 4200-second timeout only when no custom
17
+ timeout exists, enables the statusline feature on Codex CLI 0.171.0+, and selects
18
+ the xcodebug provider when the user selection is missing or `default`. Other
19
+ custom providers are preserved with a warning.
20
+ It also checks the running app-server version; both CLI and service must support
21
+ the feature. An old or unverifiable service gets a warning, not an automatic
22
+ upgrade or restart that could interrupt active tasks and captures.
23
+ From a checkout, use `node bin/xcodebug-setup-codex.mjs`. Open a new Codex session
24
+ after setup. If another custom provider was preserved, select `xcodebug_ui`
25
+ (`xcodebug / xcodebug_ui`) through `/statusline` → **Choose a status line provider**
26
+ or set `tui.status_line_provider` explicitly. If another process changes the
27
+ configuration while setup runs, the stale write is rejected; rerun setup.
28
+ See [README.md § Codex live display](README.md#codex-live-display-experimental)
29
+ for the configuration and global inventory discovery timeout details.
19
30
 
20
31
  Native pi/omp `/xcodebug` dispatches directly to the loaded extension handler,
21
32
  without skill/model selection for that dispatch. The package excludes its
package/README.md CHANGED
@@ -94,18 +94,42 @@ claude mcp list # xcodebug: … ✔ Connected
94
94
 
95
95
  After installing the package, run the setup command once to register the MCP
96
96
  server when missing and add the timeout without replacing an existing xcodebug
97
+ command or argument list:
97
98
 
98
99
  ```bash
99
100
  xcodebug-setup-codex
100
101
  ```
101
102
 
102
103
  From a checkout, use `node bin/xcodebug-setup-codex.mjs`. The command uses the
103
- Codex app-server config API. It registers xcodebug with Bun if it is missing,
104
- then writes `tool_timeout_sec = 4200`. It does not run automatically during npm
105
- install because package installation should not silently modify a user's Codex
106
- configuration. The equivalent manual setting is:
104
+ Codex app-server config API available in current Codex releases. It registers
105
+ xcodebug with Bun if it is missing, writes `tool_timeout_sec = 4200` only when
106
+ that field is absent, and preserves an existing custom timeout. On Codex CLI
107
+ `0.171.0` or later it also enables `features.tui_extensions_statusline = true`
108
+ and selects the xcodebug statusline provider when the user selection is missing
109
+ or `default`. Existing custom providers are preserved with a warning. Older or
110
+ unrecognized CLI versions receive a warning instead. It checks the
111
+ running service with `codex app-server daemon version` and warns if its
112
+ `appServerVersion` is too old or cannot be verified. Saving configuration does
113
+ not upgrade the service; setup never updates or restarts a daemon automatically.
114
+ The command warns about project-level xcodebug overrides and existing server
115
+ paths pointing elsewhere, but preserves the registration and project files.
116
+ Setup saves these fields together with one version-checked `config/batchWrite`
117
+ request.
118
+ If another process edits the user configuration during setup, Codex rejects
119
+ stale writes; rerun setup after that edit rather than overwrite a new selection.
120
+ It does not run automatically during npm install because package installation
121
+ should not silently modify a user's Codex configuration. See the live display
122
+ section below for provider selection. For manual setup on supported CLI and
123
+ app-server versions, merge these fields into existing tables rather than add
124
+ duplicate table headers:
107
125
 
108
126
  ```toml
127
+ [features]
128
+ tui_extensions_statusline = true
129
+
130
+ [tui]
131
+ status_line_provider = { server = "xcodebug", tool = "xcodebug_ui" }
132
+
109
133
  [mcp_servers.xcodebug]
110
134
  tool_timeout_sec = 4200
111
135
  ```
@@ -131,14 +155,35 @@ for the stdio integration tests.
131
155
 
132
156
  ### Codex live display (experimental)
133
157
 
134
- With Codex CLI 0.171.0 or later, start Codex with
135
- `codex --enable tui_extensions_statusline` and choose `xcodebug / xcodebug_ui`
136
- under `/statusline`. Use a fresh Codex session after updating the xcodebug MCP
137
- server. For persistent opt-in, set `features.tui_extensions_statusline = true`
138
- in Codex's config (or set `tui_extensions_statusline = true` under `[features]`).
139
- Codex 0.171.0 looks up status-line providers in the user configuration. If a
140
- project config overrides the same MCP server name, remove the override or use
141
- a distinct server name for the user registration.
158
+ Both Codex CLI and the connected app server must be `0.171.0` or later. Setup
159
+ enables the feature persistently and selects xcodebug for a missing or default
160
+ provider. Alternatively start Codex with `codex --enable tui_extensions_statusline`.
161
+ If setup reports an older running
162
+ service, finish active Codex tasks and captures before running
163
+ `codex app-server daemon update --from-cli --yes`, then
164
+ `codex app-server daemon restart`. Opening a new TUI alone does not upgrade it.
165
+
166
+ Start a new Codex session after setup or after updating the service or MCP
167
+ server. If setup preserved another custom provider, open `/statusline`, enter
168
+ **Choose a status line provider**, then select `xcodebug_ui`
169
+ (`xcodebug / xcodebug_ui`). Codex 0.171.0 discovers providers from
170
+ the user configuration. A project-level override of the same MCP server name
171
+ can make the provider unavailable; remove the override or use a distinct name.
172
+
173
+ Codex 0.171.0 has a five-second provider discovery deadline. If the global MCP
174
+ inventory stalls, the picker can show only the default provider even though
175
+ xcodebug itself is available. Specify the provider directly for one session:
176
+
177
+ ```bash
178
+ codex -c 'tui.status_line_provider={server="xcodebug",tool="xcodebug_ui"}'
179
+ ```
180
+
181
+ Setup persists the provider selection for missing/default user settings. To
182
+ replace another custom provider explicitly, use the manual settings above.
183
+ Provider selection is supported configuration, not an MCP server setting.
184
+ See Codex's
185
+ [provider configuration](https://github.com/openai/codex/blob/rust-v0.171.0/codex-rs/tui/src/app/status_line_settings.rs)
186
+ and [discovery deadline](https://github.com/openai/codex/blob/rust-v0.171.0/codex-rs/tui/src/statusline_provider.rs).
142
187
 
143
188
  The footer shows the current operation or capture and its latest log line. It
144
189
  refreshes even between tool calls and clears when no operation or capture is
@@ -1,11 +1,14 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  import { createInterface } from "node:readline";
4
+ import { existsSync, readFileSync } from "node:fs";
4
5
  import { fileURLToPath } from "node:url";
5
6
  import { dirname, join } from "node:path";
6
7
  import { spawn, spawnSync } from "node:child_process";
7
8
 
8
9
  const TOOL_TIMEOUT_SECONDS = 4_200;
10
+ const STATUSLINE_MIN_CODEX_VERSION = [0, 171, 0];
11
+ const STATUSLINE_FEATURE = "features.tui_extensions_statusline";
9
12
  const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
10
13
  const serverPath = join(packageRoot, "mcp", "server.ts");
11
14
  const codex = process.env.CODEX_BIN ?? "codex";
@@ -17,9 +20,13 @@ function run(command, args) {
17
20
  return result;
18
21
  }
19
22
 
23
+ function getRegistration() {
24
+ return run(codex, ["mcp", "get", "xcodebug"]);
25
+ }
26
+
20
27
  function ensureServerRegistration() {
21
- const existing = run(codex, ["mcp", "get", "xcodebug"]);
22
- if (existing.status === 0) return;
28
+ const existing = getRegistration();
29
+ if (existing.status === 0) return existing;
23
30
 
24
31
  const runtimeCheck = run(runtime, ["--version"]);
25
32
  if (runtimeCheck.status !== 0) {
@@ -29,6 +36,148 @@ function ensureServerRegistration() {
29
36
  if (added.status !== 0) {
30
37
  throw new Error((added.stderr || added.stdout || "codex mcp add failed").trim());
31
38
  }
39
+ const registered = getRegistration();
40
+ if (registered.status !== 0) {
41
+ throw new Error((registered.stderr || registered.stdout || "could not read the new xcodebug registration").trim());
42
+ }
43
+ return registered;
44
+ }
45
+
46
+ function projectOverrides() {
47
+ const configs = [];
48
+ for (let dir = process.cwd();; dir = dirname(dir)) {
49
+ const path = join(dir, ".codex", "config.toml");
50
+ try {
51
+ if (existsSync(path)) {
52
+ const text = readFileSync(path, "utf8");
53
+ if (/^\s*\[mcp_servers\.xcodebug\]\s*$/m.test(text) || (/^\s*\[mcp_servers\]\s*$/m.test(text) && /^\s*xcodebug\s*=/m.test(text))) configs.push(path);
54
+ }
55
+ } catch {
56
+ // A config that cannot be read is reported by Codex itself; setup must not edit it.
57
+ }
58
+ const parent = dirname(dir);
59
+ if (parent === dir) break;
60
+ }
61
+ return configs;
62
+ }
63
+
64
+ function reportWarnings(registration) {
65
+ for (const path of projectOverrides()) {
66
+ console.error(`Warning: project Codex config may override xcodebug: ${path}`);
67
+ }
68
+ if (registration.stdout && !registration.stdout.includes(serverPath)) {
69
+ console.error(`Warning: existing xcodebug registration points elsewhere; setup kept it: ${serverPath}`);
70
+ }
71
+ }
72
+
73
+ function hasTimeout(registration) {
74
+ return /^\s*tool_timeout_sec\s*:/m.test(registration.stdout);
75
+ }
76
+
77
+ function parseVersion(text) {
78
+ const match = text.match(/\b(\d+)\.(\d+)\.(\d+)\b/);
79
+ return match ? match.slice(1).map(Number) : undefined;
80
+ }
81
+
82
+ function codexVersion() {
83
+ const result = run(codex, ["--version"]);
84
+ if (result.status !== 0) return undefined;
85
+ return parseVersion(result.stdout);
86
+ }
87
+
88
+ function versionSupportsStatusline(version) {
89
+ return version[0] > STATUSLINE_MIN_CODEX_VERSION[0] ||
90
+ (version[0] === STATUSLINE_MIN_CODEX_VERSION[0] && (version[1] > STATUSLINE_MIN_CODEX_VERSION[1] ||
91
+ (version[1] === STATUSLINE_MIN_CODEX_VERSION[1] && version[2] >= STATUSLINE_MIN_CODEX_VERSION[2])));
92
+ }
93
+
94
+ function supportsStatusline() {
95
+ const version = codexVersion();
96
+ if (!version) {
97
+ console.error("Warning: could not determine Codex version; statusline feature was not enabled");
98
+ return false;
99
+ }
100
+ const supported = versionSupportsStatusline(version);
101
+ if (!supported) {
102
+ console.error(`Warning: Codex ${version.join(".")} is older than 0.171.0; statusline feature was not enabled`);
103
+ }
104
+ return supported;
105
+ }
106
+
107
+ function checkAppServerVersion() {
108
+ try {
109
+ const result = run(codex, ["app-server", "daemon", "version"]);
110
+ if (result.status !== 0) throw new Error((result.stderr || result.stdout || "daemon version query failed").trim());
111
+ const report = JSON.parse(result.stdout);
112
+ if (report?.status !== "running" || typeof report.appServerVersion !== "string") {
113
+ throw new Error("no running app-server version was reported");
114
+ }
115
+ const version = parseVersion(report.appServerVersion);
116
+ if (!version) throw new Error(`unrecognized app-server version: ${report.appServerVersion}`);
117
+ console.log(`Running Codex app-server version: ${report.appServerVersion}`);
118
+ if (!versionSupportsStatusline(version)) {
119
+ console.error(`Warning: running Codex app-server ${report.appServerVersion} is older than 0.171.0; saving the feature setting does not upgrade the server.`);
120
+ console.error("Finish active Codex tasks and captures before running:");
121
+ console.error(" codex app-server daemon update --from-cli --yes");
122
+ console.error(" codex app-server daemon restart");
123
+ }
124
+ } catch (error) {
125
+ console.error(`Warning: running Codex app-server version could not be verified: ${error instanceof Error ? error.message : String(error)}`);
126
+ console.error("If you use the shared daemon, start Codex and check with codex app-server daemon version.");
127
+ }
128
+ }
129
+
130
+ async function writeConfig(values) {
131
+ const app = startAppServer();
132
+ try {
133
+ await app.request("initialize", { clientInfo: { name: "xcodebug-setup-codex", version: "1" } });
134
+ app.child.stdin.write('{"jsonrpc":"2.0","method":"initialized"}\n');
135
+ const edits = [];
136
+ for (const keyPath of Object.keys(values)) {
137
+ edits.push({ keyPath, value: values[keyPath], mergeStrategy: "upsert" });
138
+ }
139
+ let providerSelected = false;
140
+ let filePath;
141
+ let expectedVersion;
142
+ if (values[STATUSLINE_FEATURE] === true) {
143
+ const response = await app.request("config/read", { includeLayers: true });
144
+ const userLayer = Array.isArray(response?.layers)
145
+ ? response.layers.find(layer => layer.name?.type === "user" && layer.name.profile === null && !layer.disabledReason)
146
+ : undefined;
147
+ if (!userLayer || typeof userLayer.name.file !== "string" || typeof userLayer.version !== "string" ||
148
+ !userLayer.config || typeof userLayer.config !== "object" || Array.isArray(userLayer.config)) {
149
+ throw new Error("Codex did not return user configuration metadata; statusline provider was not changed");
150
+ }
151
+ filePath = userLayer.name.file;
152
+ expectedVersion = userLayer.version;
153
+ const provider = userLayer.config.tui?.status_line_provider;
154
+ if (provider === undefined || provider === null || provider === "default") {
155
+ edits.push({ keyPath: "tui.status_line_provider", value: { server: "xcodebug", tool: "xcodebug_ui" }, mergeStrategy: "upsert" });
156
+ providerSelected = true;
157
+ } else if (provider.server !== "xcodebug" || provider.tool !== "xcodebug_ui") {
158
+ console.error("Warning: existing custom Codex statusline provider preserved; choose xcodebug_ui under /statusline or set tui.status_line_provider explicitly.");
159
+ }
160
+ }
161
+ // Codex 0.171.0 returns a non-reusable version after numeric writes; batch the edits.
162
+ const result = await app.request("config/batchWrite", { edits, filePath, expectedVersion });
163
+ if (result?.status !== "ok") throw new Error(`Codex rejected the config write: ${JSON.stringify(result)}`);
164
+ if (providerSelected) console.log("Configured Codex statusline provider: xcodebug / xcodebug_ui");
165
+ } finally {
166
+ await app.close();
167
+ }
168
+ }
169
+
170
+ async function configureCodex(registration) {
171
+ const values = {};
172
+ if (!hasTimeout(registration)) values["mcp_servers.xcodebug.tool_timeout_sec"] = TOOL_TIMEOUT_SECONDS;
173
+ if (supportsStatusline()) values[STATUSLINE_FEATURE] = true;
174
+ if (Object.keys(values).length > 0) await writeConfig(values);
175
+ if (hasTimeout(registration)) console.log("Existing Codex xcodebug tool timeout preserved");
176
+ else console.log(`Configured xcodebug MCP timeout: ${TOOL_TIMEOUT_SECONDS}s`);
177
+ if (values[STATUSLINE_FEATURE] === true) {
178
+ console.log("Enabled Codex xcodebug statusline feature in configuration");
179
+ checkAppServerVersion();
180
+ }
32
181
  }
33
182
 
34
183
  function startAppServer() {
@@ -68,24 +217,12 @@ function startAppServer() {
68
217
  });
69
218
  };
70
219
  return { child, request, close, get stderr() { return stderr; } };
71
- }
72
220
 
221
+ }
73
222
  try {
74
- ensureServerRegistration();
75
- const app = startAppServer();
76
- try {
77
- await app.request("initialize", { clientInfo: { name: "xcodebug-setup-codex", version: "1" } });
78
- app.child.stdin.write('{"jsonrpc":"2.0","method":"initialized"}\n');
79
- const result = await app.request("config/value/write", {
80
- keyPath: "mcp_servers.xcodebug.tool_timeout_sec",
81
- value: TOOL_TIMEOUT_SECONDS,
82
- mergeStrategy: "upsert",
83
- });
84
- if (result?.status !== "ok") throw new Error(`Codex rejected the config write: ${JSON.stringify(result)}`);
85
- console.log(`Configured xcodebug MCP timeout: ${TOOL_TIMEOUT_SECONDS}s`);
86
- } finally {
87
- await app.close();
88
- }
223
+ const registration = ensureServerRegistration();
224
+ reportWarnings(registration);
225
+ await configureCodex(registration);
89
226
  } catch (error) {
90
227
  console.error(`xcodebug setup-codex failed: ${error instanceof Error ? error.message : String(error)}`);
91
228
  process.exitCode = 1;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xcodebug",
3
- "version": "1.2.3",
3
+ "version": "1.2.4",
4
4
  "type": "module",
5
5
  "description": "Build, install and launch an iOS app on a physical device and read its console inside the agent session (pi / omp extension)",
6
6
  "keywords": [