Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): keep absolute builtin paths out of skills-list ignore rules (#4537)

Nick Gomezcd64a392ae7d
diff --git a/.changeset/skills-list-ignores-absolute-paths.md b/.changeset/skills-list-ignores-absolute-paths.md
new file mode 100644
index 000000000..239e1ac8c
--- /dev/null
+++ b/.changeset/skills-list-ignores-absolute-paths.md
@@ -0,0 +1,5 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+`GET /api/skills` no longer fails with a 500 when built-in skill bundles resolve to their source assets (fresh checkout or mid-build). The built-in row is now consistently listed as not ignored instead of inheriting ignore state from a build-artifact path segment.
diff --git a/packages/app/tests/integration/skills-in-place-list.test.ts b/packages/app/tests/integration/skills-in-place-list.test.ts
index 114885552..277a5d979 100644
--- a/packages/app/tests/integration/skills-in-place-list.test.ts
+++ b/packages/app/tests/integration/skills-in-place-list.test.ts
@@ -788,9 +788,19 @@ describe('in-place skill install fan-out (R13 inversion)', () => {
cpSync(join(contentDir, '.claude/skills/fanout'), codex, { recursive: true });
expect(lstatSync(codex).isSymbolicLink()).toBe(false);
- const list = (await (await fetch(`${base()}/api/skills?scope=project`)).json()) as {
+ const listRes = await fetch(`${base()}/api/skills?scope=project`);
+ expect(
+ listRes.status,
+ `expected 200 from GET /api/skills?scope=project after rewrite, got HTTP ${listRes.status}`,
+ ).toBe(200);
+ const list = (await listRes.json()) as {
skills: Array<{ name: string; driftPaths?: string[] }>;
};
+ const listKeys = Object.keys(list).join(', ');
+ expect(
+ Array.isArray(list.skills),
+ `expected a skills array from GET /api/skills?scope=project, got body keys [${listKeys}]`,
+ ).toBe(true);
const entry = list.skills.find((s) => s.name === 'fanout');
expect(entry?.driftPaths).toEqual(['.codex/skills/fanout']);
expect(lstatSync(codex).isSymbolicLink()).toBe(false);
@@ -807,9 +817,19 @@ describe('in-place skill install fan-out (R13 inversion)', () => {
});
expect(reflip.status).toBe(200);
expect(lstatSync(codex).isSymbolicLink()).toBe(true);
- const list2 = (await (await fetch(`${base()}/api/skills?scope=project`)).json()) as {
+ const list2Res = await fetch(`${base()}/api/skills?scope=project`);
+ expect(
+ list2Res.status,
+ `expected 200 from GET /api/skills?scope=project after re-flip, got HTTP ${list2Res.status}`,
+ ).toBe(200);
+ const list2 = (await list2Res.json()) as {
skills: Array<{ name: string; driftPaths?: string[] }>;
};
+ const list2Keys = Object.keys(list2).join(', ');
+ expect(
+ Array.isArray(list2.skills),
+ `expected a skills array from GET /api/skills?scope=project, got body keys [${list2Keys}]`,
+ ).toBe(true);
expect(list2.skills.find((s) => s.name === 'fanout')?.driftPaths).toBeUndefined();
});
diff --git a/packages/server/src/content-filter.test.ts b/packages/server/src/content-filter.test.ts
index 7553ba735..77f3e1630 100644
--- a/packages/server/src/content-filter.test.ts
+++ b/packages/server/src/content-filter.test.ts
@@ -1822,6 +1822,42 @@ describe('ContentFilter', () => {
expect(filter.isPathIgnored('a/b/node_modules/c/img.png')).toBe(true);
});
+ function assertAbsolutePathNonAdmission(filter: ContentFilter): void {
+ const admits = (relativePath: string): boolean => {
+ try {
+ return filter.isPathIgnored(relativePath) === false;
+ } catch {
+ return false;
+ }
+ };
+ const secretBearing = join(projectDir, 'deploy/secrets/.env');
+ const distSegment = join(projectDir, 'packages/server/dist/assets/skills/project/SKILL.md');
+ const noStructuralAnswer = join(projectDir, 'packages/server/assets/skills/project/SKILL.md');
+
+ expect(
+ filter.isPathIgnored(secretBearing),
+ `absolute secret-bearing basename ${secretBearing}: isSecretBearingFile answers before the matcher is consulted`,
+ ).toBe(true);
+ expect(
+ filter.isPathIgnored(distSegment),
+ `absolute dist-segment path ${distSegment}: the BUILTIN_SKIP_DIRS scan answers before the matcher is consulted`,
+ ).toBe(true);
+ expect(
+ admits(noStructuralAnswer),
+ `absolute path with no structural answer ${noStructuralAnswer}: the shared closure must not admit input it cannot classify, so consult sites must gate before consulting`,
+ ).toBe(false);
+ }
+
+ test('does not admit absolute paths it cannot classify, and keeps the structural answers that precede the matcher', () => {
+ assertAbsolutePathNonAdmission(createContentFilter({ projectDir, contentDir: projectDir }));
+ });
+
+ test('async factory (createContentFilterAsync) mirrors absolute-path non-admission', async () => {
+ assertAbsolutePathNonAdmission(
+ await createContentFilterAsync({ projectDir, contentDir: projectDir }),
+ );
+ });
+
test('rejects paths matched by .gitignore patterns', () => {
writeFileSync(join(projectDir, '.gitignore'), 'tmp/\n*.bak.png\n');
diff --git a/packages/server/src/http/skills-list-routes.test.ts b/packages/server/src/http/skills-list-routes.test.ts
index 1a3428175..adfecfedf 100644
--- a/packages/server/src/http/skills-list-routes.test.ts
+++ b/packages/server/src/http/skills-list-routes.test.ts
@@ -1,9 +1,15 @@
-import { describe, expect, test } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { type ContentFilter, createContentFilter } from '../content-filter.ts';
import { loggerFactory } from '../logger.ts';
+import { BUNDLE_SKILL_NAME } from '../skill-bundles.ts';
import { createSkillsCatalogCache } from '../skills-catalog-cache.ts';
-import { createSkillsListRoutes } from './skills-list-routes.ts';
+import { createSkillsListRoutes, type SkillsListRouteDeps } from './skills-list-routes.ts';
-function buildGroup() {
+function buildGroup(overrides: Partial<SkillsListRouteDeps> = {}) {
return createSkillsListRoutes({
contentDir: '/nonexistent-content',
projectDir: undefined,
@@ -25,6 +31,7 @@ function buildGroup() {
builtinSkillListEntry: () => null,
indexedSkillContentPath: () => null,
healUnservableSkillAdmission: () => Promise.resolve(false),
+ ...overrides,
});
}
@@ -40,3 +47,205 @@ describe('createSkillsListRoutes table', () => {
}
});
});
+
+type BuiltinAssetCandidate = 'dist bundle asset' | 'committed source asset';
+
+describe('createSkillsListRoutes builtin-row ignore-rule contract', () => {
+ const BUNDLED_ASSET_SEGMENTS: Record<BuiltinAssetCandidate, string[]> = {
+ 'dist bundle asset': ['dist', 'assets', 'skills', 'project', 'SKILL.md'],
+ 'committed source asset': ['assets', 'skills', 'project', 'SKILL.md'],
+ };
+
+ const probeCases: Array<{ assetCandidate: BuiltinAssetCandidate; heals: boolean }> = [
+ { assetCandidate: 'dist bundle asset', heals: false },
+ { assetCandidate: 'dist bundle asset', heals: true },
+ ];
+
+ let tmpDir: string;
+ let skillsHome: string;
+
+ beforeEach(() => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'ok-skills-list-routes-'));
+ skillsHome = join(tmpDir, 'skills-home');
+ mkdirSync(skillsHome, { recursive: true });
+ });
+
+ afterEach(() => {
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ function recordingContentFilter(): { contentFilter: ContentFilter; consultedPaths: string[] } {
+ const consultedPaths: string[] = [];
+ const contentFilter = {
+ isPathIgnored: (relativePath: string) => {
+ consultedPaths.push(relativePath);
+ return true;
+ },
+ peekFreshInPlaceSkillDirsFingerprint: () => '',
+ } as ContentFilter;
+ return { contentFilter, consultedPaths };
+ }
+
+ function builtinRowEmitter(bundledSkillMd: string): SkillsListRouteDeps['builtinSkillListEntry'] {
+ return (_base, name, scope) => {
+ if (scope !== 'project') return null;
+ return {
+ name,
+ scope,
+ path: bundledSkillMd,
+ absolutePath: bundledSkillMd,
+ installed: false,
+ hosts: [],
+ managed: true,
+ };
+ };
+ }
+
+ async function readSkillsListResponse(group: ReturnType<typeof createSkillsListRoutes>): Promise<{
+ status: number;
+ body: string;
+ }> {
+ const dispatch = group.table.resolve('/api/skills')?.dispatch;
+ const captured = { status: 0, body: '' };
+ const res = {
+ writeHead(status: number) {
+ captured.status = status;
+ },
+ end(body?: string) {
+ captured.body = body ?? '';
+ },
+ } as unknown as ServerResponse;
+ const req = { method: 'GET', url: '/api/skills', headers: {} } as unknown as IncomingMessage;
+ await dispatch?.(req, res);
+ return captured;
+ }
+
+ test.each(probeCases)(
+ 'builtin bundle row ($assetCandidate, healing pass: $heals): ignore rules never see its absolute path and it lists unflagged',
+ async ({ assetCandidate, heals }) => {
+ const bundledSkillMd = join(
+ tmpDir,
+ 'packages',
+ 'server',
+ ...BUNDLED_ASSET_SEGMENTS[assetCandidate],
+ );
+ const { contentFilter, consultedPaths } = recordingContentFilter();
+ const group = buildGroup({
+ contentDir: tmpDir,
+ projectDir: tmpDir,
+ skillsHome,
+ contentFilter,
+ builtinSkillListEntry: builtinRowEmitter(bundledSkillMd),
+ healUnservableSkillAdmission: () => Promise.resolve(heals),
+ });
+
+ const captured = await readSkillsListResponse(group);
+
+ expect(
+ captured.status,
+ `expected 200 from the skills list handler, got HTTP ${captured.status} with body ${captured.body}`,
+ ).toBe(200);
+ const parsed = JSON.parse(captured.body) as {
+ skills?: Array<{ name: string; ignored?: boolean }>;
+ };
+ expect(
+ Array.isArray(parsed.skills),
+ `expected a skills array in the list response, got body keys [${Object.keys(parsed).join(', ')}]`,
+ ).toBe(true);
+ const skills = parsed.skills ?? [];
+ const rowNames = skills.map((s) => s.name);
+ const builtinRow = skills.find((s) => s.name === BUNDLE_SKILL_NAME.project);
+ expect(
+ builtinRow,
+ `expected the builtin bundle row ${BUNDLE_SKILL_NAME.project} in the list response, got rows [${rowNames.join(', ')}]`,
+ ).toBeDefined();
+ const absoluteConsultations = consultedPaths.filter((p) => isAbsolute(p));
+ expect(
+ absoluteConsultations,
+ `isPathIgnored was consulted with absolute path(s) [${absoluteConsultations.join(', ')}]; the skills-list enrichment and its post-heal re-map must not feed absolute paths to ignore rules`,
+ ).toEqual([]);
+ expect(
+ builtinRow?.ignored,
+ `expected the builtin bundle row ${BUNDLE_SKILL_NAME.project} to be listed without ignored: true, got ignored=${builtinRow?.ignored}`,
+ ).not.toBe(true);
+ },
+ );
+
+ test.each([{ heals: false }, { heals: true }])(
+ 'builtin bundle row with the real filter, committed source asset (healing pass: $heals): both route guards keep the matcher from seeing the absolute path',
+ async ({ heals }) => {
+ const bundledSkillMd = join(
+ tmpDir,
+ 'packages',
+ 'server',
+ ...BUNDLED_ASSET_SEGMENTS['committed source asset'],
+ );
+ const contentFilter = createContentFilter({ projectDir: tmpDir, contentDir: tmpDir });
+ const group = buildGroup({
+ contentDir: tmpDir,
+ projectDir: tmpDir,
+ skillsHome,
+ contentFilter,
+ builtinSkillListEntry: builtinRowEmitter(bundledSkillMd),
+ healUnservableSkillAdmission: () => Promise.resolve(heals),
+ });
+
+ const captured = await readSkillsListResponse(group);
+
+ expect(
+ captured.status,
+ `expected 200: the route declines to consult the filter with the row's absolute path, so the matcher is never asked to classify input it cannot, got HTTP ${captured.status} with body ${captured.body}`,
+ ).toBe(200);
+ const parsed = JSON.parse(captured.body) as {
+ skills?: Array<{ name: string; ignored?: boolean }>;
+ };
+ const builtinRow = parsed.skills?.find((s) => s.name === BUNDLE_SKILL_NAME.project);
+ expect(
+ builtinRow,
+ `expected the builtin bundle row ${BUNDLE_SKILL_NAME.project} in the list response, got rows [${(parsed.skills ?? []).map((s) => s.name).join(', ')}]`,
+ ).toBeDefined();
+ expect(
+ builtinRow?.ignored,
+ `expected the builtin bundle row ${BUNDLE_SKILL_NAME.project} to list without ignored: true when the route declines to consult the filter with its absolute path, got ignored=${builtinRow?.ignored}`,
+ ).not.toBe(true);
+ },
+ );
+
+ test('builtin bundle row with the real filter, dist-segment shape: the filter would answer ignored via its segment scan, the route deliberately lists it unflagged', async () => {
+ const bundledSkillMd = join(
+ tmpDir,
+ 'packages',
+ 'server',
+ ...BUNDLED_ASSET_SEGMENTS['dist bundle asset'],
+ );
+ const contentFilter = createContentFilter({ projectDir: tmpDir, contentDir: tmpDir });
+ expect(
+ contentFilter.isPathIgnored(bundledSkillMd),
+ 'contrast: consulted directly, the filter answers true for this shape via its BUILTIN_SKIP_DIRS segment scan',
+ ).toBe(true);
+
+ const group = buildGroup({
+ contentDir: tmpDir,
+ projectDir: tmpDir,
+ skillsHome,
+ contentFilter,
+ builtinSkillListEntry: builtinRowEmitter(bundledSkillMd),
+ healUnservableSkillAdmission: () => Promise.resolve(false),
+ });
+
+ const captured = await readSkillsListResponse(group);
+
+ expect(
+ captured.status,
+ `expected 200, got HTTP ${captured.status} with body ${captured.body}`,
+ ).toBe(200);
+ const parsed = JSON.parse(captured.body) as {
+ skills?: Array<{ name: string; ignored?: boolean }>;
+ };
+ const builtinRow = parsed.skills?.find((s) => s.name === BUNDLE_SKILL_NAME.project);
+ expect(
+ builtinRow?.ignored,
+ `the route declines to consult the filter for paths outside its classification domain and answers unflagged at the API, got ignored=${builtinRow?.ignored}`,
+ ).not.toBe(true);
+ });
+});
diff --git a/packages/server/src/http/skills-list-routes.ts b/packages/server/src/http/skills-list-routes.ts
index ae329f3ca..fefd30ba3 100644
--- a/packages/server/src/http/skills-list-routes.ts
+++ b/packages/server/src/http/skills-list-routes.ts
@@ -1,5 +1,5 @@
import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
import {
AGENTS_SKILLS_ROOT,
EmptyRequestSchema,
@@ -456,7 +456,9 @@ export function createSkillsListRoutes(deps: SkillsListRouteDeps): ApiRouteGroup
? withFiles
: { ...withFiles, canonicalPath };
const openedPath = canonicalPath ?? entry.path;
- return entry.scope === 'project' && contentFilter?.isPathIgnored(openedPath) === true
+ return entry.scope === 'project' &&
+ !isAbsolute(openedPath) &&
+ contentFilter?.isPathIgnored(openedPath) === true
? { ...withCanonical, ignored: true }
: withCanonical;
}),
@@ -474,7 +476,8 @@ export function createSkillsListRoutes(deps: SkillsListRouteDeps): ApiRouteGroup
skills: enriched.skills.map((entry) => {
if (entry.scope !== 'project') return entry;
const opened = (entry as { canonicalPath?: string }).canonicalPath ?? entry.path;
- const nowIgnored = contentFilter?.isPathIgnored(opened) === true;
+ const nowIgnored =
+ !isAbsolute(opened) && contentFilter?.isPathIgnored(opened) === true;
const wasIgnored = (entry as { ignored?: boolean }).ignored === true;
if (nowIgnored === wasIgnored) return entry;
if (nowIgnored) return { ...entry, ignored: true };