Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 {