Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): group repo-declared plugin skills in every checkout (PRD-8261) (#3840)
tim-inkeepcdc92d752c87
diff --git a/.changeset/prd-8261-repo-marketplace-plugin-groups.md b/.changeset/prd-8261-repo-marketplace-plugin-groups.mdnew file mode 100644index 000000000..0385ffb60--- /dev/null+++ b/.changeset/prd-8261-repo-marketplace-plugin-groups.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Skills served by a plugin the repo itself declares (a `.claude-plugin/marketplace.json` with in-tree plugin sources) now group under that plugin in every checkout of the repo. Grouping previously depended on the editor's plugin registry, which records installs per absolute path, so a second clone of the same repo showed those skills as a flat, ungrouped list. The repo manifest is now read directly, so the identity no longer depends on where the clone lives or whether the editor has registered it.diff --git a/packages/app/tests/integration/skills-in-place-list.test.ts b/packages/app/tests/integration/skills-in-place-list.test.tsindex 068df1a08..9f9ef72f4 100644--- a/packages/app/tests/integration/skills-in-place-list.test.ts+++ b/packages/app/tests/integration/skills-in-place-list.test.ts@@ -1,4 +1,12 @@-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ rmSync,+ symlinkSync,+ writeFileSync,+} from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import { afterEach, beforeEach, describe, expect, test } from 'vitest';@@ -1568,3 +1576,51 @@ describe('outsideProject stamp on /api/skills/installed', () => {expect(found?.outsideProject).toBe(true);});});++describe('repo-declared plugin identity on /api/skills (no harness registry)', () => {+ let contentDir: string;+ let server: TestServer;++ beforeEach(async () => {+ contentDir = mkdtempSync(join(tmpdir(), 'ok-repo-plugin-'));+ mkdirSync(join(contentDir, '.claude-plugin'), { recursive: true });+ writeFileSync(+ join(contentDir, '.claude-plugin', 'marketplace.json'),+ JSON.stringify({ name: 'repo-mkt', plugins: [{ name: 'tools', source: './plugins/tools' }] }),+ );+ mkdirSync(join(contentDir, '.claude'), { recursive: true });+ writeFileSync(+ join(contentDir, '.claude', 'settings.json'),+ JSON.stringify({ enabledPlugins: { 'tools@repo-mkt': true } }),+ );+ mkdirSync(join(contentDir, 'plugins/tools/.claude-plugin'), { recursive: true });+ writeFileSync(+ join(contentDir, 'plugins/tools/.claude-plugin/plugin.json'),+ JSON.stringify({ name: 'tools', repository: 'https://github.com/acme/tools' }),+ );+ writeSkill(contentDir, 'plugins/tools/skills/served', '# Served by the plugin');+ mkdirSync(join(contentDir, '.agents/skills'), { recursive: true });+ symlinkSync('../../plugins/tools/skills/served', join(contentDir, '.agents/skills/served'));+ writeSkill(contentDir, '.agents/skills/handmade', '# Hand-authored');+ server = await createTestServer({ contentDir });+ });+ afterEach(async () => {+ await server.cleanup();+ rmSync(contentDir, { recursive: true, force: true });+ });++ test('a symlinked in-repo plugin skill carries the plugin; a hand-authored sibling does not', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/skills?scope=project`);+ expect(res.status).toBe(200);+ const { skills } = (await res.json()) as {+ skills: Array<{ name: string; plugin?: Record<string, unknown> }>;+ };+ expect(skills.find((s) => s.name === 'served')?.plugin).toEqual({+ name: 'tools',+ marketplace: 'repo-mkt',+ provider: 'claude',+ url: 'https://github.com/acme/tools',+ });+ expect(skills.find((s) => s.name === 'handmade')?.plugin).toBeUndefined();+ });+});diff --git a/packages/core/src/skills-catalog/index.ts b/packages/core/src/skills-catalog/index.tsindex 7bf41a5c1..7299175af 100644--- a/packages/core/src/skills-catalog/index.ts+++ b/packages/core/src/skills-catalog/index.ts@@ -94,6 +94,11 @@ export type {} from './plugin-providers/types.ts';export { type PluginUpstream, pluginUpstreamsByName } from './plugin-upstream.ts';export { parseSkillsShPublisherPage } from './publisher.ts';+export {+ type RepoMarketplacePlugin,+ readRepoMarketplacePlugins,+ repoMarketplacePluginFor,+} from './repo-marketplace.ts';export { parseGitHubRepoSearch, parseOpenGraph, parseSkillsShSearch } from './search.ts';export {buildSkillRegistry,diff --git a/packages/core/src/skills-catalog/plugin-providers/manifest-providers.ts b/packages/core/src/skills-catalog/plugin-providers/manifest-providers.tsindex 0ae8c4db5..c7be32f1b 100644--- a/packages/core/src/skills-catalog/plugin-providers/manifest-providers.ts+++ b/packages/core/src/skills-catalog/plugin-providers/manifest-providers.ts@@ -149,7 +149,7 @@ export function enumerateAgentPluginsRoot(}/** The manifest's optional `repository` URL, or null. */-function manifestRepositoryUrl(dir: string, rel: string): string | null {+export function manifestRepositoryUrl(dir: string, rel: string): string | null {try {const parsed = JSON.parse(readFileSync(join(dir, rel), 'utf-8')) as { repository?: unknown };return typeof parsed.repository === 'string' && parsed.repository.length > 0diff --git a/packages/core/src/skills-catalog/plugin-upstream.ts b/packages/core/src/skills-catalog/plugin-upstream.tsindex f4cfd730a..1e512b354 100644--- a/packages/core/src/skills-catalog/plugin-upstream.ts+++ b/packages/core/src/skills-catalog/plugin-upstream.ts@@ -44,9 +44,16 @@ export interface PluginUpstream {* their copies are already first-class rows elsewhere — treating one as an* upstream would let a skill become its own origin.*- * First writer wins for a duplicated name, matching the order the detected list- * itself resolves duplicates in, so the two surfaces cannot disagree about which- * plugin owns a name.+ * First writer wins for a duplicated name. The `/api/skills` index is built from+ * the machine-wide enumeration (a copy of a plugin's skill is that plugin's+ * wherever the copy sits, and the registry keys project installs by checkout+ * path), while `/api/skills/installed` stays project-scoped, so name-only+ * consumers may resolve a different plugin for a name than the detected list+ * would. That covers more than the Modified badge: the synthesized lock entry's+ * source is the plugin cache dir, and a reimport fetches from it, so a name+ * collision across project-scoped plugins on one machine could overwrite a+ * hand-authored skill in another project on an explicit reimport. The+ * realpath-verified identity path is unaffected.*/export function pluginUpstreamsByName(skills: readonly CatalogSkill[],diff --git a/packages/core/src/skills-catalog/repo-marketplace.test.ts b/packages/core/src/skills-catalog/repo-marketplace.test.tsnew file mode 100644index 000000000..6bbb7e679--- /dev/null+++ b/packages/core/src/skills-catalog/repo-marketplace.test.ts@@ -0,0 +1,105 @@+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { readRepoMarketplacePlugins, repoMarketplacePluginFor } from './repo-marketplace.ts';++let repo: string;++beforeEach(() => {+ repo = mkdtempSync(join(tmpdir(), 'ok-repo-marketplace-'));+ mkdirSync(join(repo, '.claude-plugin'));+ writeFileSync(+ join(repo, '.claude-plugin', 'marketplace.json'),+ JSON.stringify({+ name: 'inkeep-agents-private',+ plugins: [+ { name: 'agents', source: './public/agents/plugins/agents' },+ { name: 'remote', source: 'github:foo/bar' },+ { name: 'missing', source: './nowhere' },+ // Resolves on disk, so only the in-tree guard can exclude it.+ { name: 'absolute', source: join(repo, 'public/agents/plugins/agents') },+ // Declared and on disk, but the repo does not enable it.+ { name: 'disabled', source: './public/agents/plugins/agents' },+ // Enabled but the dir is gone (uninitialized submodule, mid-rename).+ { name: 'phantom', source: './phantom' },+ // Relative, but climbs out of the tree.+ { name: 'escape', source: '../outside-plugin' },+ ],+ }),+ );+ mkdirSync(join(repo, '.claude'));+ writeFileSync(+ join(repo, '.claude', 'settings.json'),+ JSON.stringify({+ enabledPlugins: {+ 'agents@inkeep-agents-private': true,+ 'absolute@inkeep-agents-private': true,+ 'disabled@inkeep-agents-private': false,+ 'phantom@inkeep-agents-private': true,+ 'escape@inkeep-agents-private': true,+ },+ }),+ );+ mkdirSync(join(repo, 'public/agents/plugins/agents/.claude-plugin'), { recursive: true });+ writeFileSync(+ join(repo, 'public/agents/plugins/agents/.claude-plugin/plugin.json'),+ JSON.stringify({ name: 'agents', repository: 'https://github.com/inkeep/agents-private' }),+ );+ mkdirSync(join(repo, 'public/agents/plugins/agents/skills/write-docs'), { recursive: true });+ mkdirSync(join(repo, 'public/agents/plugins/agents/references/not-a-skill'), { recursive: true });+ mkdirSync(join(repo, '.agents/skills'), { recursive: true });+ symlinkSync(+ '../../public/agents/plugins/agents/skills/write-docs',+ join(repo, '.agents/skills/write-docs'),+ );+ mkdirSync(join(repo, '.agents/skills/hand-authored'));+ mkdirSync(join(repo, '..', 'outside-plugin', 'skills'), { recursive: true });+});++afterEach(() => {+ rmSync(repo, { recursive: true, force: true });+ rmSync(join(repo, '..', 'outside-plugin'), { recursive: true, force: true });+});++describe('repo-declared marketplace plugins', () => {+ it('keeps only in-tree, enabled plugin roots, with the plugin.json repository as url', () => {+ const plugins = readRepoMarketplacePlugins(repo);+ expect(plugins.map((p) => p.name)).toEqual(['agents']);+ expect(plugins[0]).toMatchObject({+ marketplace: 'inkeep-agents-private',+ url: 'https://github.com/inkeep/agents-private',+ });+ });++ it('identifies a symlinked in-repo plugin skill; leaves a hand-authored one alone', () => {+ const plugins = readRepoMarketplacePlugins(repo);+ expect(repoMarketplacePluginFor(plugins, join(repo, '.agents/skills/write-docs'))?.name).toBe(+ 'agents',+ );+ expect(+ repoMarketplacePluginFor(plugins, join(repo, '.agents/skills/hand-authored')),+ ).toBeNull();+ expect(repoMarketplacePluginFor(plugins, join(repo, '.agents/skills/gone'))).toBeNull();+ expect(+ repoMarketplacePluginFor(+ plugins,+ join(repo, 'public/agents/plugins/agents/references/not-a-skill'),+ ),+ ).toBeNull();+ });++ it('is empty without a manifest, and without enabledPlugins', () => {+ expect(readRepoMarketplacePlugins(join(repo, 'public'))).toEqual([]);+ rmSync(join(repo, '.claude', 'settings.json'));+ expect(readRepoMarketplacePlugins(repo)).toEqual([]);+ });++ it('warns on a malformed manifest instead of treating it as absent', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ writeFileSync(join(repo, '.claude-plugin', 'marketplace.json'), '{ not json');+ expect(readRepoMarketplacePlugins(repo)).toEqual([]);+ expect(warn).toHaveBeenCalledTimes(1);+ warn.mockRestore();+ });+});diff --git a/packages/core/src/skills-catalog/repo-marketplace.ts b/packages/core/src/skills-catalog/repo-marketplace.tsnew file mode 100644index 000000000..680e13c5a--- /dev/null+++ b/packages/core/src/skills-catalog/repo-marketplace.ts@@ -0,0 +1,112 @@+import { readFileSync, realpathSync } from 'node:fs';+import { isAbsolute, join, resolve, sep } from 'node:path';+import { manifestRepositoryUrl } from './plugin-providers/manifest-providers.ts';++/** A plugin the open repo itself declares, resolved to its on-disk root. */+export interface RepoMarketplacePlugin {+ readonly name: string;+ readonly marketplace: string;+ /** Realpath of the plugin's root dir; skills live at `<root>/skills/<name>`. */+ readonly rootReal: string;+ readonly url?: string;+}++/**+ * Plugins declared by the open tree's own `.claude-plugin/marketplace.json`.+ *+ * A repo that hosts its marketplace serves these plugins in place, so a skill+ * under one of their roots IS the plugin's skill regardless of whether the+ * user's harness registry knows about this checkout. The registry is keyed by+ * absolute path: a second clone of the same repo has no entries there, the+ * identity join through `enumerateInstalledSkills` comes up empty, and every+ * in-repo plugin skill read as hand-authored. The manifest is the authority the+ * registry was only echoing, so read it directly.+ *+ * Only relative (in-tree) `source` entries count; a marketplace entry pointing+ * at a remote or absolute source is not served from this tree. And only plugins+ * the repo ENABLES count: the identity feeds a "Claude already loads this via+ * the plugin" claim downstream, and declaring a plugin does not make a harness+ * load it — `.claude/settings.json` `enabledPlugins` does.+ */+export function readRepoMarketplacePlugins(contentDir: string): RepoMarketplacePlugin[] {+ let manifest: { name?: unknown; plugins?: Array<{ name?: unknown; source?: unknown }> };+ try {+ manifest = JSON.parse(+ readFileSync(join(contentDir, '.claude-plugin', 'marketplace.json'), 'utf-8'),+ );+ } catch (err) {+ warnUnlessMissing(err, 'failed to read repo marketplace manifest, skipping', contentDir);+ return [];+ }+ if (typeof manifest?.name !== 'string' || !Array.isArray(manifest.plugins)) return [];+ let contentReal: string;+ try {+ contentReal = realpathSync(contentDir);+ } catch (err) {+ warnUnlessMissing(err, 'failed to resolve the content dir, skipping repo plugins', contentDir);+ return [];+ }+ const enabled = readEnabledPlugins(contentDir);+ const out: RepoMarketplacePlugin[] = [];+ for (const p of manifest.plugins) {+ if (typeof p?.name !== 'string' || typeof p?.source !== 'string') continue;+ if (isAbsolute(p.source) || /^[a-z]+:/i.test(p.source)) continue;+ if (enabled[`${p.name}@${manifest.name}`] !== true) continue;+ let rootReal: string;+ try {+ rootReal = realpathSync(resolve(contentDir, p.source));+ } catch (err) {+ // ENOENT is the phantom case (uninitialized submodule, mid-rename) and stays quiet.+ warnUnlessMissing(err, `failed to resolve plugin root for ${p.name}, skipping`, contentDir);+ continue;+ }+ // A relative source can still climb out (`../sibling`); that dir is not this tree's.+ if (!rootReal.startsWith(`${contentReal}${sep}`)) continue;+ // No plugin.json is fine: the marketplace entry alone is enough for identity.+ const url = manifestRepositoryUrl(rootReal, '.claude-plugin/plugin.json');+ out.push({ name: p.name, marketplace: manifest.name, rootReal, ...(url ? { url } : {}) });+ }+ return out;+}++/** An absent file is the common case and stays silent; a malformed or unreadable+ * one silently zeroes out every repo plugin, so it gets a warning an operator can+ * tell apart from "nothing declared" (same posture as the enumerator). */+function warnUnlessMissing(err: unknown, msg: string, contentDir: string): void {+ if ((err as NodeJS.ErrnoException | null)?.code === 'ENOENT') return;+ console.warn(`[skills-catalog] ${msg}`, { contentDir, err });+}++/** `enabledPlugins` from the repo's shared `.claude/settings.json`; `{}` when absent or unreadable. */+function readEnabledPlugins(contentDir: string): Record<string, unknown> {+ try {+ const settings = JSON.parse(+ readFileSync(join(contentDir, '.claude', 'settings.json'), 'utf-8'),+ ) as { enabledPlugins?: unknown };+ const e = settings.enabledPlugins;+ return e && typeof e === 'object' ? (e as Record<string, unknown>) : {};+ } catch (err) {+ warnUnlessMissing(+ err,+ 'failed to read .claude/settings.json, no repo plugins enabled',+ contentDir,+ );+ return {};+ }+}++/** The repo-declared plugin whose `skills/` dir holds `skillAbsDir` (symlinks resolved), or null. */+export function repoMarketplacePluginFor(+ plugins: readonly RepoMarketplacePlugin[],+ skillAbsDir: string,+): RepoMarketplacePlugin | null {+ if (plugins.length === 0) return null;+ let real: string;+ try {+ real = realpathSync(skillAbsDir);+ } catch (err) {+ warnUnlessMissing(err, 'failed to resolve skill dir', skillAbsDir);+ return null;+ }+ return plugins.find((p) => real.startsWith(`${p.rootReal}${sep}skills${sep}`)) ?? null;+}diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex ea1531abc..4936ff171 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -290,8 +290,10 @@ import {parseSource,pluginRepositoryUrl,pluginUpstreamsByName,+ readRepoMarketplacePlugins,readSkillDirMeta,readWellKnownIndex,+ repoMarketplacePluginFor,resolvePluginUpdateSource,resolveSkillsShImportSource,retrofitPackLockEntry,@@ -14368,11 +14370,14 @@ export function createApiExtension(try {// Enumeration and hashing are the IO; the join itself is pure and lives in// core, where it can be tested without a plugin cache on disk.+ // Deliberately NOT scoped to the project: a copy of a plugin's skill is a+ // copy of that plugin wherever the copy sits, and the registry keys+ // project-scoped installs by absolute checkout path, so scoping left a+ // second clone of the same repo with no upstream for any of its copies.byName = pluginUpstreamsByName(- enumerateInstalledSkillsCached({- projectDir: identity,- ...(homeDirOverride !== undefined ? { home: homeDirOverride } : {}),- }).skills,+ enumerateInstalledSkillsCached(+ homeDirOverride !== undefined ? { home: homeDirOverride } : {},+ ).skills,(home) => parseSkillDir(home)?.contentHash,);} catch (err) {@@ -15162,6 +15167,22 @@ export function createApiExtension(// read as untracked. Attributing it to every same-named row would put a// Revert button on a skill whose baseline belongs to a different one.const projectNameSeen = new Set<string>();+ // The repo's own marketplace manifest is the second identity source:+ // the registry join above is keyed by absolute checkout path, so a+ // second clone of the same repo has no records there and its in-repo+ // plugin skills would read as hand-authored.+ const repoPlugins = readRepoMarketplacePlugins(contentDir);+ const repoPluginIdentity = (dir: string) => {+ const p = repoMarketplacePluginFor(repoPlugins, dir);+ return p+ ? {+ name: p.name,+ marketplace: p.marketplace,+ provider: 'claude',+ ...(p.url ? { url: p.url } : {}),+ }+ : null;+ };const inPlace = projectDir? scanInPlaceSkills(contentDir).map((s) => {const tracked = !projectNameSeen.has(s.name);@@ -15176,7 +15197,8 @@ export function createApiExtension(// Identity beats provenance: a skill that IS a plugin's skill// carries the plugin, never an origin.const selfPlugin = tracked- ? pluginSelfIdentity(s.name, detectedIdentity, skillAbsDir)+ ? (pluginSelfIdentity(s.name, detectedIdentity, skillAbsDir) ??+ repoPluginIdentity(skillAbsDir)): null;const entry =tracked && selfPlugin === null@@ -15311,7 +15333,8 @@ export function createApiExtension(if (!tracked) return {};// Same two synthesized fallbacks as the project site: a built-in// carries its skills.sh origin, a copy of a plugin's skill carries- // the plugin.+ // the plugin. The repo-manifest identity is project-only: a global+ // skill is not tree-local, so no repo can serve it in place.const globalAbsDir = resolve(skillsHome, s.dir);const selfPluginGlobal = pluginSelfIdentity(s.name, detectedIdentity, globalAbsDir);if (selfPluginGlobal !== null) return { plugin: selfPluginGlobal };