Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-10142 Report a missing skill opener instead of crashing (#7958)

Andrew Mikofalvy3f2a422c93b4
diff --git a/.changeset/cowork-skill-missing-opener.md b/.changeset/cowork-skill-missing-opener.md
new file mode 100644
index 000000000..a417253e5
--- /dev/null
+++ b/.changeset/cowork-skill-missing-opener.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Building the Claude Cowork skill no longer crashes the server or `ok cowork` when the system file opener is missing, such as Linux without `xdg-open`. `ok cowork` says the file was built but not opened.
diff --git a/packages/cli/src/commands/cowork.test.ts b/packages/cli/src/commands/cowork.test.ts
index 21da2dd8c..b87a6d2b5 100644
--- a/packages/cli/src/commands/cowork.test.ts
+++ b/packages/cli/src/commands/cowork.test.ts
@@ -1,4 +1,5 @@
import type { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
import { existsSync, mkdtempSync, rmSync, statSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
@@ -14,7 +15,9 @@ function makeFakeSpawn(capture: {
if (capture.threw) throw capture.threw;
capture.command = command;
capture.args = args;
- return { unref: () => {} } as unknown as ReturnType<typeof spawn>;
+ const child = Object.assign(new EventEmitter(), { unref: () => {} });
+ queueMicrotask(() => child.emit('spawn'));
+ return child as unknown as ReturnType<typeof spawn>;
}) as unknown as typeof spawn;
}
diff --git a/packages/server/src/skill-install.test.ts b/packages/server/src/skill-install.test.ts
index 95d7aef3a..89a4b5ed1 100644
--- a/packages/server/src/skill-install.test.ts
+++ b/packages/server/src/skill-install.test.ts
@@ -1,4 +1,5 @@
-import type { SpawnOptions } from 'node:child_process';
+import { type SpawnOptions, spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
import { readFile } from 'node:fs/promises';
import { join } from 'node:path';
@@ -42,6 +43,12 @@ function freshHome(): string {
return makeTempDir('ok-skill-install-');
}
+function spawnedChild(): ReturnType<SpawnLike> {
+ const child = Object.assign(new EventEmitter(), { unref: () => {} });
+ queueMicrotask(() => child.emit('spawn'));
+ return child as unknown as ReturnType<SpawnLike>;
+}
+
function installHost(home: string, hostDir: string): void {
mkdirSync(join(home, hostDir), { recursive: true });
}
@@ -533,7 +540,7 @@ describe('buildAndOpenSkill', () => {
capture.command = command;
capture.args = args;
capture.opts = opts;
- return { unref: () => {} } as ReturnType<SpawnLike>;
+ return spawnedChild();
}) as SpawnLike;
}
@@ -640,6 +647,52 @@ describe('buildAndOpenSkill', () => {
expect(result.handoffError?.message).toContain('EACCES');
expect(result.outputPath).toBeDefined();
});
+
+ test('a missing opener fails asynchronously: status="built" with handoffError reason=spawn-error', async () => {
+ const home = freshHome();
+ const missingOpener = join(home, 'no-such-opener');
+ const spawned: string[] = [];
+
+ const result = await buildAndOpenSkill({
+ home,
+ out: join(home, 'missing-opener.skill'),
+ platformName: 'linux',
+ spawnFn: ((command: string, args: readonly string[], opts: SpawnOptions) => {
+ spawned.push(command);
+ return spawn(missingOpener, args, opts);
+ }) as SpawnLike,
+ });
+
+ expect(spawned).toEqual(['xdg-open']);
+ expect(result).toMatchObject({
+ status: 'built',
+ outputPath: join(home, 'missing-opener.skill'),
+ handoffError: {
+ reason: 'spawn-error',
+ message: expect.stringMatching(/^No system file opener \(xdg-open\) was found: .*ENOENT/),
+ },
+ });
+ });
+
+ test('an opener that exists but cannot run is reported with its own error, not as missing', async (ctx) => {
+ ctx.skip(process.platform === 'win32', 'exec permission bits are POSIX-only');
+ const home = freshHome();
+ const unrunnableOpener = join(home, 'unrunnable-opener');
+ writeFileSync(unrunnableOpener, 'not a program\n', { mode: 0o644 });
+
+ const result = await buildAndOpenSkill({
+ home,
+ out: join(home, 'unrunnable-opener.skill'),
+ platformName: 'linux',
+ spawnFn: ((_command: string, args: readonly string[], opts: SpawnOptions) =>
+ spawn(unrunnableOpener, args, opts)) as SpawnLike,
+ });
+
+ expect(result.status).toBe('built');
+ expect(result.handoffError?.reason).toBe('spawn-error');
+ expect(result.handoffError?.message).toContain(unrunnableOpener);
+ expect(result.handoffError?.message).not.toMatch(/^No system file opener/);
+ });
});
describe('buildAndOpenSkill — install-state gate', () => {
@@ -711,10 +764,8 @@ describe('buildAndOpenSkill — install-state gate', () => {
spawnFn: ((command: string, args: readonly string[]) => {
capture.command = command;
capture.args = args;
- return {
- unref: () => {},
- } as unknown as ReturnType<Parameters<SpawnLike>[2] extends never ? never : SpawnLike>;
- }) as unknown as SpawnLike,
+ return spawnedChild();
+ }) as SpawnLike,
force: true,
});
diff --git a/packages/server/src/skill-install.ts b/packages/server/src/skill-install.ts
index 02ca43863..2d44ce08d 100644
--- a/packages/server/src/skill-install.ts
+++ b/packages/server/src/skill-install.ts
@@ -18,6 +18,7 @@ import {
} from './build-skill-zip.ts';
import { withHiddenWindowsConsole } from './child-process-windows-hide.ts';
import { tracedCpSync, tracedMkdir, tracedMkdirSync, tracedRmSync } from './fs-traced.ts';
+import { errnoCode } from './http/handler-utils.ts';
import { getLogger } from './logger.ts';
import { BUNDLE_SKILL_NAME, type BundleId } from './skill-bundles.ts';
import { recordSkillInstallEvent, type SkillInstallEventOutcome } from './skill-install-events.ts';
@@ -388,40 +389,61 @@ function defaultDownloadsPath(home: string): string {
return join(home, DOWNLOADS_DIR, SKILL_FILENAME);
}
+type FileAssociationOutcome =
+ | { ok: true }
+ | { ok: false; reason: 'unsupported-platform' | 'spawn-error'; message: string };
+
+function fileAssociationCommand(
+ skillPath: string,
+ platformName: NodeJS.Platform,
+): { command: string; args: string[] } | undefined {
+ if (platformName === 'darwin') return { command: 'open', args: [skillPath] };
+ if (platformName === 'win32') return { command: 'cmd', args: ['/c', 'start', '""', skillPath] };
+ if (platformName === 'linux') return { command: 'xdg-open', args: [skillPath] };
+ return undefined;
+}
+
+function spawnErrorOutcome(command: string, err: unknown): FileAssociationOutcome {
+ const detail = err instanceof Error ? err.message : String(err);
+ const missing = errnoCode(err) === 'ENOENT';
+ return {
+ ok: false,
+ reason: 'spawn-error',
+ message: missing ? `No system file opener (${command}) was found: ${detail}` : detail,
+ };
+}
+
function invokeFileAssociation(
skillPath: string,
platformName: NodeJS.Platform,
spawnFn: SpawnLike,
-): { ok: true } | { ok: false; reason: 'unsupported-platform' | 'spawn-error'; message: string } {
+): Promise<FileAssociationOutcome> {
+ const invocation = fileAssociationCommand(skillPath, platformName);
+ if (invocation === undefined) {
+ return Promise.resolve({
+ ok: false,
+ reason: 'unsupported-platform',
+ message: `Platform '${platformName}' has no file-association invocation wired.`,
+ });
+ }
const detached: SpawnOptions = withHiddenWindowsConsole({
detached: true,
stdio: 'ignore',
});
- try {
- if (platformName === 'darwin') {
- spawnFn('open', [skillPath], detached).unref();
- return { ok: true };
- }
- if (platformName === 'win32') {
- spawnFn('cmd', ['/c', 'start', '""', skillPath], detached).unref();
- return { ok: true };
- }
- if (platformName === 'linux') {
- spawnFn('xdg-open', [skillPath], detached).unref();
- return { ok: true };
+ return new Promise((resolve) => {
+ let child: ReturnType<SpawnLike>;
+ try {
+ child = spawnFn(invocation.command, invocation.args, detached);
+ } catch (err) {
+ resolve(spawnErrorOutcome(invocation.command, err));
+ return;
}
- return {
- ok: false,
- reason: 'unsupported-platform',
- message: `Platform '${platformName}' has no file-association invocation wired.`,
- };
- } catch (err) {
- return {
- ok: false,
- reason: 'spawn-error',
- message: err instanceof Error ? err.message : String(err),
- };
- }
+ child.on('error', (err) => resolve(spawnErrorOutcome(invocation.command, err)));
+ child.once('spawn', () => {
+ child.unref();
+ resolve({ ok: true });
+ });
+ });
}
export async function buildAndOpenSkill(
@@ -562,7 +584,7 @@ export async function buildAndOpenSkill(
return baseResult;
}
- const invocation = invokeFileAssociation(build.outputPath, platformName, spawnFn);
+ const invocation = await invokeFileAssociation(build.outputPath, platformName, spawnFn);
if (!invocation.ok) {
await report('built', installedVersion, `handoff-${invocation.reason}`);
return {