Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix: stabilize Windows artifact opener

tt-a1ic2d70fa0c9ee
diff --git a/archify/bin/open-artifact.mjs b/archify/bin/open-artifact.mjs
index b8559cfc..5a042b73 100644
--- a/archify/bin/open-artifact.mjs
+++ b/archify/bin/open-artifact.mjs
@@ -5,16 +5,22 @@ const OPENERS = {
darwin: {
command: 'open',
method: 'open',
+ timeoutMs: 5000,
args: (target) => [target],
},
linux: {
command: 'xdg-open',
method: 'xdg-open',
+ timeoutMs: 5000,
args: (target) => [target],
},
win32: {
command: 'powershell.exe',
method: 'powershell',
+ // PowerShell cold starts can approach five seconds on hosted Windows
+ // runners. Keep the launch bounded without treating normal startup as a
+ // timeout.
+ timeoutMs: 15000,
// Keep the command constant and pass the target through a child-only
// environment variable. Paths are never interpolated into executable source.
args: () => [
@@ -26,6 +32,51 @@ const OPENERS = {
},
};
+function failureDetails(result, opener, timeoutMs) {
+ const error = result?.error;
+ if (error?.code === 'ENOENT') {
+ return {
+ code: 'opener/unavailable',
+ reason: `Could not find ${opener.command}. Install or enable the platform opener, then open the target manually.`,
+ systemCode: 'ENOENT',
+ };
+ }
+ if (error?.code === 'ETIMEDOUT') {
+ return {
+ code: 'opener/timeout',
+ reason: `${opener.command} did not finish within ${timeoutMs}ms. Open the target manually or retry when the system is less busy.`,
+ systemCode: 'ETIMEDOUT',
+ timeoutMs,
+ };
+ }
+ if (error) {
+ return {
+ code: 'opener/spawn-failed',
+ reason: error.message || `${opener.command} could not be started. Open the target manually.`,
+ ...(error.code ? { systemCode: String(error.code) } : {}),
+ };
+ }
+ if (result?.signal) {
+ return {
+ code: 'opener/signaled',
+ reason: `${opener.command} was terminated by ${result.signal}. Open the target manually.`,
+ signal: result.signal,
+ };
+ }
+ if (result?.status !== 0) {
+ return {
+ code: 'opener/nonzero-exit',
+ reason: `${opener.command} exited with status ${result?.status ?? 'unknown'}. Open the target manually.`,
+ exitCode: result?.status ?? null,
+ };
+ }
+ return null;
+}
+
+function launchTimeout(value, fallback) {
+ return Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
function launchTarget(target, options = {}) {
const platform = options.platform || process.platform;
const opener = OPENERS[platform];
@@ -39,13 +90,14 @@ function launchTarget(target, options = {}) {
}
const spawn = options.spawn || spawnSync;
+ const timeoutMs = launchTimeout(options.timeoutMs, opener.timeoutMs);
let result;
try {
const spawnOptions = {
encoding: 'utf8',
shell: false,
stdio: 'ignore',
- timeout: options.timeoutMs || 5000,
+ timeout: timeoutMs,
windowsHide: true,
};
if (platform === 'win32') {
@@ -55,19 +107,21 @@ function launchTarget(target, options = {}) {
};
}
result = spawn(opener.command, opener.args(target), spawnOptions);
- } catch {
- result = { error: new Error('opener threw') };
+ } catch (error) {
+ result = { error };
}
+ const failure = failureDetails(result, opener, timeoutMs);
let status = 'opened';
- if (result?.error?.code === 'ENOENT') status = 'unsupported';
- else if (result?.error || result?.signal || result?.status !== 0) status = 'failed';
+ if (failure?.code === 'opener/unavailable') status = 'unsupported';
+ else if (failure) status = 'failed';
return {
requested: true,
status,
target,
method: opener.method,
+ ...(failure ? { failure } : {}),
};
}
diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.md
index 0cd8e43e..85368d9c 100644
--- a/archify/references/delivery-contract.md
+++ b/archify/references/delivery-contract.md
@@ -359,8 +359,11 @@ a capable environment.
Add `--open` only when the user wants an immediate local preview. It runs after
the verified pair commit has completed, its recovery journal has been removed,
and the delivery lock has been released successfully. It uses one argument-array
-OS opener with a five-second bound and records `open.status`. Keep it off for CI, unattended agents, and non-interactive
-environments. Failure or unsupported opening does not invalidate delivery; its
+OS opener with a five-second bound on macOS and Linux, and a fifteen-second bound
+for PowerShell startup on Windows. The receipt records `open.status`; failed or
+unavailable launch attempts also include normalized `open.failure` details.
+Keep it off for CI, unattended agents, and non-interactive environments.
+Failure or unsupported opening does not invalidate delivery; its
status proves only whether the local opener invocation succeeded.
## Last-Good Live Preview
diff --git a/archify/test/open-artifact.test.mjs b/archify/test/open-artifact.test.mjs
index 41adf774..299e8c22 100644
--- a/archify/test/open-artifact.test.mjs
+++ b/archify/test/open-artifact.test.mjs
@@ -52,7 +52,7 @@ test('open artifact: uses argument arrays without shell interpolation on every s
assert.equal(invocation.command, expected.command);
assert.deepEqual(invocation.args, expected.args);
assert.equal(invocation.options.shell, false);
- assert.equal(invocation.options.timeout, 5000);
+ assert.equal(invocation.options.timeout, expected.platform === 'win32' ? 15000 : 5000);
if (expected.platform === 'win32') {
assert.equal(invocation.options.env.ARCHIFY_OPEN_TARGET, target);
} else {
@@ -75,26 +75,107 @@ test('open artifact: Windows PowerShell launches a real target', { skip: process
});
});
-test('open artifact: distinguishes missing support from opener execution failure', () => {
+test('open artifact: normalizes missing opener and timeout failures', () => {
const missing = openArtifact(target, {
platform: 'linux',
spawn() {
return { error: Object.assign(new Error('missing'), { code: 'ENOENT' }) };
},
});
- assert.equal(missing.status, 'unsupported');
- assert.equal(missing.method, 'xdg-open');
+ assert.deepEqual(missing, {
+ requested: true,
+ status: 'unsupported',
+ target,
+ method: 'xdg-open',
+ failure: {
+ code: 'opener/unavailable',
+ reason: 'Could not find xdg-open. Install or enable the platform opener, then open the target manually.',
+ systemCode: 'ENOENT',
+ },
+ });
const timedOut = openArtifact(target, {
+ platform: 'win32',
+ timeoutMs: 1234,
+ spawn(command, args, options) {
+ assert.equal(options.timeout, 1234);
+ return { error: Object.assign(new Error('timed out'), { code: 'ETIMEDOUT' }) };
+ },
+ });
+ assert.deepEqual(timedOut, {
+ requested: true,
+ status: 'failed',
+ target,
+ method: 'powershell',
+ failure: {
+ code: 'opener/timeout',
+ reason: 'powershell.exe did not finish within 1234ms. Open the target manually or retry when the system is less busy.',
+ systemCode: 'ETIMEDOUT',
+ timeoutMs: 1234,
+ },
+ });
+});
+
+test('open artifact: invalid timeout overrides retain the bounded platform default', () => {
+ for (const timeoutMs of [0, -1, 1.5, Number.NaN, Number.POSITIVE_INFINITY, '1000']) {
+ let observedTimeout;
+ const result = openArtifact(target, {
+ platform: 'win32',
+ timeoutMs,
+ spawn(command, args, options) {
+ observedTimeout = options.timeout;
+ return { status: 0 };
+ },
+ });
+ assert.equal(result.status, 'opened');
+ assert.equal(observedTimeout, 15000, String(timeoutMs));
+ }
+});
+
+test('open artifact: normalizes nonzero exits, signals, and thrown spawn errors', () => {
+ const nonzero = openArtifact(target, {
platform: 'darwin',
spawn() {
- return { error: Object.assign(new Error('timed out'), { code: 'ETIMEDOUT' }) };
+ return { status: 7 };
},
});
- assert.equal(timedOut.status, 'failed');
- assert.equal(timedOut.method, 'open');
+ assert.deepEqual(nonzero.failure, {
+ code: 'opener/nonzero-exit',
+ reason: 'open exited with status 7. Open the target manually.',
+ exitCode: 7,
+ });
+ const signaled = openArtifact(target, {
+ platform: 'linux',
+ spawn() {
+ return { status: null, signal: 'SIGTERM' };
+ },
+ });
+ assert.deepEqual(signaled.failure, {
+ code: 'opener/signaled',
+ reason: 'xdg-open was terminated by SIGTERM. Open the target manually.',
+ signal: 'SIGTERM',
+ });
+
+ const denied = openArtifact(target, {
+ platform: 'linux',
+ spawn() {
+ throw Object.assign(new Error('permission denied'), { code: 'EACCES' });
+ },
+ });
+ assert.deepEqual(denied.failure, {
+ code: 'opener/spawn-failed',
+ reason: 'permission denied',
+ systemCode: 'EACCES',
+ });
+ for (const result of [nonzero, signaled, denied]) {
+ assert.equal(result.status, 'failed');
+ }
+});
+
+test('open artifact: unsupported platforms retain the public result shape', () => {
const unknown = openArtifact(target, { platform: 'plan9' });
+
assert.deepEqual(unknown, {
requested: true,
status: 'unsupported',