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 +15 -4
- package/README.md +57 -12
- package/bin/xcodebug-setup-codex.mjs +155 -18
- package/package.json +1 -1
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
|
|
16
|
-
the server when missing
|
|
17
|
-
|
|
18
|
-
|
|
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
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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 =
|
|
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
|
-
|
|
76
|
-
|
|
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