Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): install starter-pack skills in the packaged app (PRD-8048) (#3626)

tim-inkeep0ce24b2db9fb
diff --git a/.changeset/pack-skill-asar-copy.md b/.changeset/pack-skill-asar-copy.md
new file mode 100644
index 000000000..5640e9463
--- /dev/null
+++ b/.changeset/pack-skill-asar-copy.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Starter packs now install their skills in the packaged desktop app. Seeding a pack wrote its folders, templates and root files but installed none of the pack's skills — picking the Knowledge base pack left `.claude/skills/` holding only the platform `open-knowledge` skill, with no `knowledge-base`, `research-with-sources` or `consolidate-notes`. The pack's skill sources ship inside the app's `app.asar` archive, and the recursive copy the installer used cannot read out of that archive, so every copy failed and the seed carried on without them. The installer now copies through the same archive-aware walk the rest of the skill machinery uses. Pack skills carry the guidance that tells agents how to work in the folders a pack creates, so until now every packaged pack install shipped the layout without the behavior.
diff --git a/packages/server/src/copy-dir.test.ts b/packages/server/src/copy-dir.test.ts
new file mode 100644
index 000000000..36485f227
--- /dev/null
+++ b/packages/server/src/copy-dir.test.ts
@@ -0,0 +1,63 @@
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, test } from 'vitest';
+import { copyDirSync } from './copy-dir.ts';
+
+function tmpDir(): string {
+ return mkdtempSync(join(tmpdir(), 'ok-copy-dir-'));
+}
+
+/** A pack-skill-shaped source: a root bundle with a nested member skill. */
+function seedSource(): string {
+ const src = join(tmpDir(), 'pack');
+ mkdirSync(join(src, 'references'), { recursive: true });
+ mkdirSync(join(src, 'member'), { recursive: true });
+ writeFileSync(join(src, 'SKILL.md'), 'root\n');
+ writeFileSync(join(src, 'README.md'), 'readme\n');
+ writeFileSync(join(src, 'references', 'deep.md'), 'deep\n');
+ writeFileSync(join(src, 'member', 'SKILL.md'), 'member\n');
+ return src;
+}
+
+describe('copyDirSync', () => {
+ test('copies the tree recursively, creating the destination', () => {
+ const src = seedSource();
+ const dest = join(tmpDir(), 'out');
+
+ copyDirSync(src, dest);
+
+ expect(readdirSync(dest).sort()).toEqual(['README.md', 'SKILL.md', 'member', 'references']);
+ expect(readFileSync(join(dest, 'SKILL.md'), 'utf-8')).toBe('root\n');
+ expect(readFileSync(join(dest, 'references', 'deep.md'), 'utf-8')).toBe('deep\n');
+ expect(readFileSync(join(dest, 'member', 'SKILL.md'), 'utf-8')).toBe('member\n');
+ });
+
+ test('filter skips an entry and, for a directory, its whole subtree', () => {
+ const src = seedSource();
+ const dest = join(tmpDir(), 'out');
+ const excluded = ['member', 'README.md'];
+
+ copyDirSync(src, dest, {
+ filter: (path) => !excluded.some((entry) => path === join(src, entry)),
+ });
+
+ expect(readdirSync(dest).sort()).toEqual(['SKILL.md', 'references']);
+ // The listing alone would pass even if descent into an included directory
+ // were skipped — `mkdir` creates it on entry regardless.
+ expect(readFileSync(join(dest, 'references', 'deep.md'), 'utf-8')).toBe('deep\n');
+ });
+
+ test('merges into an existing destination without failing', () => {
+ const src = seedSource();
+ const dest = join(tmpDir(), 'out');
+ mkdirSync(join(dest, 'references'), { recursive: true });
+ writeFileSync(join(dest, 'references', 'stale.md'), 'stale\n');
+
+ copyDirSync(src, dest);
+
+ expect(readFileSync(join(dest, 'references', 'deep.md'), 'utf-8')).toBe('deep\n');
+ // Callers own freshness — the copy itself never removes what it did not write.
+ expect(readFileSync(join(dest, 'references', 'stale.md'), 'utf-8')).toBe('stale\n');
+ });
+});
diff --git a/packages/server/src/copy-dir.ts b/packages/server/src/copy-dir.ts
new file mode 100644
index 000000000..743694d01
--- /dev/null
+++ b/packages/server/src/copy-dir.ts
@@ -0,0 +1,61 @@
+/**
+ * Recursive directory copy that works when the SOURCE lives inside an
+ * Electron `app.asar` archive.
+ *
+ * Electron's asar fs-shim DOES patch `cpSync` — but it patches it by extracting
+ * the single FILE at the source path out of the archive and delegating to the
+ * real `cpSync` (`overrideAPISync` in Electron's `lib/node/asar-fs-wrapper.ts`).
+ * A directory node carries no `size`/`offset`, so `Archive::CopyFileOut` fails
+ * on it and the shim itself throws `ENOENT ... not found in .../app.asar`
+ * before any recursion runs. Observable directly: `cpSync` on a FILE inside the
+ * archive succeeds, on a DIRECTORY it throws, while `existsSync`, `statSync`,
+ * `readdirSync` and `readFileSync` succeed on either. Walking the tree with
+ * those shimmed primitives is the only copy form that survives packaging, and
+ * the desktop main process reaches this module with
+ * `@inkeep/open-knowledge-server` (and its bundled `assets/skills/**`) packed
+ * inside the asar.
+ *
+ * `asarUnpack` is not the alternative: the shim consults `info.unpacked` only
+ * after the same file-info lookup that a directory node already fails.
+ *
+ * Symlinks in the source are dereferenced rather than recreated — the sources
+ * this copies are our own bundled skill assets, which hold none, and a link
+ * copied into a user's editor dir would dangle anyway.
+ *
+ * No `rmSync` here: callers that need wipe-then-copy freshness (so a bundle
+ * bump that drops a file leaves no orphan) do it at their own call site, where
+ * the symlink-escape guard also belongs.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { tracedMkdirSync, tracedWriteFileSync } from './fs-traced.ts';
+
+export interface CopyDirOptions {
+ /**
+ * Receives the absolute SOURCE path of each entry BELOW `sourceDir`; return
+ * `false` to skip it (and, for a directory, its subtree). Two deliberate
+ * departures from `cpSync`'s filter: no destination path is passed, and the
+ * predicate is never invoked for `sourceDir` itself — pruning at the root
+ * cannot cancel the copy the way it does there.
+ */
+ readonly filter?: (src: string) => boolean;
+}
+
+export function copyDirSync(
+ sourceDir: string,
+ destDir: string,
+ options: CopyDirOptions = {},
+): void {
+ tracedMkdirSync(destDir, { recursive: true });
+ for (const entry of readdirSync(sourceDir)) {
+ const src = join(sourceDir, entry);
+ if (options.filter?.(src) === false) continue;
+ const dest = join(destDir, entry);
+ if (statSync(src).isDirectory()) {
+ copyDirSync(src, dest, options);
+ } else {
+ tracedWriteFileSync(dest, readFileSync(src));
+ }
+ }
+}
diff --git a/packages/server/src/seed/install-pack-skill.test.ts b/packages/server/src/seed/install-pack-skill.test.ts
index 9cdd35c2c..58b7c1b2d 100644
--- a/packages/server/src/seed/install-pack-skill.test.ts
+++ b/packages/server/src/seed/install-pack-skill.test.ts
@@ -10,7 +10,7 @@ import {
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { OPENKNOWLEDGE_SKILLS_REPO, RENAMED_PACK_SKILLS } from '@inkeep/open-knowledge-core';
-import { describe, expect, test } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
import { readInstalledSkills } from '../installed-skills-marker.ts';
import {
classifyPresentPackSkill,
@@ -400,3 +400,32 @@ describe('classifyPresentPackSkill — ours-retrofit', () => {
rmSync(dir, { recursive: true, force: true });
});
});
+
+describe('installPackSkill — a copy that fails partway does not wedge the skill', () => {
+ test('rolls the partial tree back so a later seed retries instead of reading it as present', async () => {
+ const proj = tmpProject();
+ setUpEditor(proj, '.claude');
+ const name = orientationName('knowledge-base');
+ const skillDir = join(proj, '.claude', 'skills', name);
+
+ // Fail AFTER a file has landed — the window the walk opens and the copy
+ // primitive it replaced never could.
+ const copyDir = await import('../copy-dir.ts');
+ const real = copyDir.copyDirSync;
+ const spy = vi.spyOn(copyDir, 'copyDirSync').mockImplementationOnce((_src, dest) => {
+ mkdirSync(dest, { recursive: true });
+ writeFileSync(join(dest, 'SKILL.md'), '---\nname: half\n---\npartial\n');
+ throw Object.assign(new Error('ENOSPC: no space left on device'), { code: 'ENOSPC' });
+ });
+
+ await installPackSkill(proj, 'knowledge-base');
+ expect(existsSync(join(skillDir, 'SKILL.md'))).toBe(false);
+
+ // The retry is the point: without rollback the half-written SKILL.md reads
+ // as an already-present fork and the skill is never re-copied.
+ spy.mockRestore();
+ expect(copyDir.copyDirSync).toBe(real);
+ await installPackSkill(proj, 'knowledge-base');
+ expect(readFileSync(join(skillDir, 'SKILL.md'), 'utf-8')).not.toContain('partial');
+ });
+});
diff --git a/packages/server/src/seed/install-pack-skill.ts b/packages/server/src/seed/install-pack-skill.ts
index aadd620e6..97c84f5b9 100644
--- a/packages/server/src/seed/install-pack-skill.ts
+++ b/packages/server/src/seed/install-pack-skill.ts
@@ -36,7 +36,8 @@ import {
type SkillsLock,
upsertLockEntry,
} from '@inkeep/open-knowledge-core/skills-catalog';
-import { tracedCpSync, tracedMkdirSync, tracedRmSync, tracedWriteFileSync } from '../fs-traced.ts';
+import { copyDirSync } from '../copy-dir.ts';
+import { tracedMkdirSync, tracedRmSync, tracedWriteFileSync } from '../fs-traced.ts';
import { resolveDefaultSkillHomeRel, scanInPlaceSkills } from '../in-place-skills.ts';
import { getLogger } from '../logger.ts';
import { BUNDLE_SKILL_NAME } from '../skill-bundles.ts';
@@ -322,11 +323,21 @@ export async function installPackSkill(
tracedMkdirSync(join(projectDir, homeRel), { recursive: true });
// A decomposed pack's root dir CONTAINS its member skill dirs; each member
// installs as its own top-level skill, so filter them out of the root copy.
- tracedCpSync(sourceDir, skillDir, {
- recursive: true,
+ copyDirSync(sourceDir, skillDir, {
filter: (src) => !excludePaths.some((p) => src === join(sourceDir, p)),
});
} catch (err) {
+ // Roll back the partial tree. A walk can fail HALFWAY (unlike the copy
+ // primitive it replaced, which threw before writing anything), and a
+ // `SKILL.md` that landed before the failure would make every later seed
+ // read the skill as already present — classified as our own fork and
+ // therefore never re-copied. Best-effort: a failed rollback must not
+ // mask the original error.
+ try {
+ tracedRmSync(skillDir, { recursive: true, force: true });
+ } catch {
+ // leave the partial tree; the warn below still names the skill
+ }
// A real disk failure (EACCES / ENOSPC / I/O) — NOT the benign
// "pack ships no skill" (empty `sources` above). Log it so a seed that
// silently installed 0 editors is diagnosable rather than mistaken for normal.