dsh-agent-plugins-market 0.4.3

package/lib/discovery/manifests.js

@@ -0,0 +1,214 @@
+/**
+ * Manifest layer: detects and parses the suite-manifest dialects a checkout
+ * can carry, and resolves a repo-level name for source-id derivation.
+ *
+ * Dialects (each a JSON document at the suite root):
+ * - agent-plugin-v1: root `plugin.json` (agent-plugins.org), schema-validated;
+ * - universal: `.plugin/plugin.json`;
+ * - claude-code: `.claude-plugin/plugin.json`;
+ * - cursor: `.cursor-plugin/plugin.json`;
+ * - kimi: `.kimi-plugin/plugin.json`;
+ * - codex: `.codex-plugin/plugin.json`.
+ *
+ * The same repo can declare several dialects (e.g. vercel/vercel-plugin ships
+ * all of them); a suite's identity comes from the highest-precedence dialect
+ * present, while surfaces (skills/commands/agents/hooks/mcp) are scanned from
+ * the directories regardless of which dialect won.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { sanitizeId } from '../paths.js';
+import { isRecognizedSchema, validatePluginManifest } from '../validate.js';
+/** Dialect precedence: v1 wins over universal over claude over cursor over kimi over codex. */
+const KIND_PRECEDENCE = ['agent-plugin-v1', 'universal', 'claude-code', 'cursor', 'kimi', 'codex'];
+const MANIFEST_PATHS = {
+    'agent-plugin-v1': 'plugin.json',
+    universal: join('.plugin', 'plugin.json'),
+    'claude-code': join('.claude-plugin', 'plugin.json'),
+    cursor: join('.cursor-plugin', 'plugin.json'),
+    kimi: join('.kimi-plugin', 'plugin.json'),
+    codex: join('.codex-plugin', 'plugin.json'),
+};
+/** The highest-precedence manifest file a directory carries, if any. */
+export async function detectManifest(dir) {
+    for (const kind of KIND_PRECEDENCE) {
+        const path = join(dir, MANIFEST_PATHS[kind]);
+        try {
+            if ((await stat(path)).isFile())
+                return { kind, path };
+        }
+        catch {
+            // try the next dialect
+        }
+    }
+    return undefined;
+}
+/** Whether a directory carries any known suite manifest. */
+export async function hasSuiteManifest(dir) {
+    return (await detectManifest(dir)) !== undefined;
+}
+/** Fallback suite identity for manifest-less skill collections. */
+export function syntheticManifestName(root) {
+    return root.split(/[\\/]/).at(-1) ?? 'plugin';
+}
+/**
+ * Parse one manifest document into a normalized SuiteManifest. The v1 dialect
+ * is schema-validated (fail-closed); the others are structurally read with
+ * light tolerance, and `hint` (a marketplace plugin entry) fills in gaps.
+ */
+export async function readManifest(root, errors, hint) {
+    const candidate = await detectManifest(root);
+    if (candidate === undefined)
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(candidate.path, 'utf8'));
+    }
+    catch (error) {
+        errors.push(`${candidate.path} unparsable: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    if (typeof raw !== 'object' || raw === null) {
+        errors.push(`${candidate.path}: manifest is not a JSON object`);
+        return undefined;
+    }
+    const record = raw;
+    const problems = candidate.kind === 'agent-plugin-v1'
+        ? await validatePluginManifest(raw)
+        : [];
+    errors.push(...problems.map(problem => `${candidate.path}: ${problem}`));
+    const name = pickString(record.name) ?? hint?.name ?? syntheticManifestName(root);
+    const version = pickString(record.version) ?? hint?.version;
+    const description = pickString(record.description) ?? hint?.description;
+    const author = record.author;
+    return {
+        layout: candidate.kind === 'agent-plugin-v1' ? 'agent-plugin-v1' : candidate.kind === 'universal' ? 'universal' : candidate.kind === 'claude-code' ? 'claude-code' : candidate.kind === 'cursor' ? 'cursor' : candidate.kind === 'kimi' ? 'kimi' : 'codex',
+        path: candidate.path,
+        id: sanitizeId(name),
+        name,
+        ...version === undefined ? {} : { version },
+        ...description === undefined ? {} : { description },
+        ...(author?.name !== undefined ? { author: author.name } : pickString(record.homepage) !== undefined ? { author: pickString(record.homepage) } : {}),
+        keywords: Array.isArray(record.keywords) ? record.keywords.filter((entry) => typeof entry === 'string') : [],
+        ...isRecognizedSchema(record.$schema) ? { schemaVersion: record.$schema } : {},
+    };
+}
+function pickString(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+/** Marketplace manifest locations per dialect (Claude Code, Codex). */
+const MARKETPLACE_PATHS = ['.claude-plugin/marketplace.json', '.agents/plugins/marketplace.json'];
+/** Read a marketplace manifest from a checkout root, or undefined when absent. */
+export async function readMarketplace(checkoutDir) {
+    for (const relative of MARKETPLACE_PATHS) {
+        let text;
+        try {
+            text = await readFile(join(checkoutDir, relative), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed !== 'object' || parsed === null)
+                continue;
+            const record = parsed;
+            const plugins = record['plugins'];
+            if (!Array.isArray(plugins))
+                continue;
+            return {
+                ...typeof record['name'] === 'string' ? { name: record['name'] } : {},
+                entries: plugins,
+            };
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+/** Resolve one marketplace entry to a local checkout-relative directory, or
+ *  `undefined` for remote-URL entries that are not present in the clone. */
+export function marketplaceEntryDir(checkoutDir, entry) {
+    const source = entry.source;
+    if (typeof source === 'string')
+        return resolve(checkoutDir, source);
+    if (source?.path !== undefined)
+        return resolve(checkoutDir, source.path);
+    return undefined;
+}
+/**
+ * Resolve a repo-level name for source-id derivation, in precedence order:
+ * marketplace plugin entry name > marketplace name > root manifest name >
+ * the checkout basename. The suite repo's own JSON is authoritative; the
+ * basename is only the fallback.
+ */
+export async function repoName(checkoutDir) {
+    const marketplace = await readMarketplace(checkoutDir);
+    if (marketplace !== undefined) {
+        const entries = marketplace.entries;
+        if (entries.length === 1) {
+            // A single-suite marketplace: the plugin entry names the repo (vercel → vercel-plugin).
+            const entryName = pickString(entries[0].name);
+            if (entryName !== undefined)
+                return entryName;
+        }
+        const marketplaceName = pickString(marketplace.name);
+        if (marketplaceName !== undefined)
+            return marketplaceName;
+        if (entries.length === 1) {
+            const entryName = pickString(entries[0].name);
+            if (entryName !== undefined)
+                return entryName;
+        }
+    }
+    const candidate = await detectManifest(checkoutDir);
+    if (candidate !== undefined) {
+        try {
+            const raw = JSON.parse(await readFile(candidate.path, 'utf8'));
+            if (typeof raw === 'object' && raw !== null) {
+                const name = raw['name'];
+                if (typeof name === 'string' && name !== '')
+                    return name;
+            }
+        }
+        catch {
+            // fall through to basename
+        }
+    }
+    return syntheticManifestName(checkoutDir);
+}
+/** The winning manifest's declared `skills` path (string or array), or undefined. */
+export async function declaredSkillsPath(root) {
+    const candidate = await detectManifest(root);
+    if (candidate === undefined)
+        return undefined;
+    try {
+        const raw = JSON.parse(await readFile(candidate.path, 'utf8'));
+        if (typeof raw === 'object' && raw !== null) {
+            return raw['skills'];
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+/** The winning manifest's inline `mcpServers`, or undefined. */
+export async function declaredMcpServers(root) {
+    const candidate = await detectManifest(root);
+    if (candidate === undefined)
+        return undefined;
+    try {
+        const raw = JSON.parse(await readFile(candidate.path, 'utf8'));
+        if (typeof raw === 'object' && raw !== null) {
+            const servers = raw['mcpServers'];
+            if (typeof servers === 'object' && servers !== null)
+                return servers;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}

package/lib/discovery/surfaces.js

@@ -0,0 +1,232 @@
+/**
+ * Surface layer: scans a suite root's content directories — skills, mcp,
+ * commands, agents, hooks, lsp — into normalized previews and counts.
+ *
+ * Skills honor any path the winning manifest declares (`skills` may be a
+ * string, an array, or absent), scan up to three levels of nesting, and
+ * dedupe by frontmatter name. MCP reads both `mcp.json` and the dot-prefixed
+ * `.mcp.json`, tolerating unknown transports per server. Every read is
+ * fail-closed: broken files produce a diagnostic and are skipped, never a
+ * thrown discovery.
+ */
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseSkillFrontmatter } from '../skills-parse.js';
+import { isDirectory } from '../paths.js';
+import { validateMcpJson } from '../validate.js';
+import { declaredMcpServers } from './manifests.js';
+const DOT_DIRS = new Set(['.git', '.github', '.claude', '.cursor', '.kimi', '.plugin', '.sources', 'node_modules']);
+/** Resolve a manifest-declared skills path into absolute directories (string or array form). */
+function declaredSkillDirs(root, declared) {
+    const values = Array.isArray(declared) ? declared : [declared];
+    const dirs = [];
+    for (const value of values) {
+        if (typeof value !== 'string' || value === '')
+            continue;
+        const cleaned = value.replace(/^\.\//, '');
+        const path = join(root, cleaned);
+        if (isAbsoluteWithin(root, path))
+            dirs.push(path);
+    }
+    return dirs;
+}
+function isAbsoluteWithin(root, candidate) {
+    return candidate.startsWith(`${root}${candidate.includes('/') ? '/' : '\\'}`) || candidate.startsWith(root);
+}
+/** Discover SKILL.md files under the suite's skills directory, up to 3 levels deep. */
+export async function discoverSkills(root, errors, declared) {
+    const skills = [];
+    const rootSkill = join(root, 'SKILL.md');
+    const rootName = root.split(/[\\/]/).at(-1) ?? 'plugin';
+    const rootParsed = await parseOneSkill(rootSkill, root, rootName, errors);
+    if (rootParsed !== undefined)
+        skills.push(rootParsed);
+    const skillsDirs = declaredSkillDirs(root, declared);
+    if (skillsDirs.length === 0) {
+        const fallback = join(root, 'skills');
+        if (await isDirectory(fallback))
+            skillsDirs.push(fallback);
+    }
+    const seen = new Set();
+    const pushUnique = (skill) => {
+        if (skill === undefined || seen.has(skill.name))
+            return;
+        seen.add(skill.name);
+        skills.push(skill);
+    };
+    for (const skillsDir of skillsDirs) {
+        // A declared path may be one skill directory (a manifest listing
+        // individual skills, e.g. mattpocock) or a container of skills.
+        if (await isFile(join(skillsDir, 'SKILL.md'))) {
+            const name = skillsDir.split(/[\\/]/).at(-1) ?? '';
+            pushUnique(await parseOneSkill(join(skillsDir, 'SKILL.md'), skillsDir, name, errors));
+            continue;
+        }
+        for (const child of await listChildDirs(skillsDir)) {
+            const name = child.split(/[\\/]/).at(-1) ?? '';
+            pushUnique(await parseOneSkill(join(child, 'SKILL.md'), child, name, errors));
+        }
+        // Category-nested collections and upstream mirrors (depth 3).
+        for (const category of await listChildDirs(skillsDir)) {
+            for (const child of await listChildDirs(category)) {
+                const name = child.split(/[\\/]/).at(-1) ?? '';
+                pushUnique(await parseOneSkill(join(child, 'SKILL.md'), child, name, errors));
+            }
+        }
+    }
+    return skills;
+}
+async function parseOneSkill(file, directory, fallbackName, errors) {
+    if (!await isFile(file))
+        return undefined;
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        errors.push(`skill "${fallbackName}": unreadable SKILL.md (${error instanceof Error ? error.message : String(error)})`);
+        return undefined;
+    }
+    const parsed = parseSkillFrontmatter(text, undefined);
+    if (typeof parsed === 'string') {
+        errors.push(`skill "${fallbackName}": ${parsed}`);
+        return undefined;
+    }
+    return {
+        name: parsed.name,
+        directory,
+        file,
+        description: parsed.description,
+        ...parsed.whenToUse === undefined ? {} : { whenToUse: parsed.whenToUse },
+        invocation: parsed.invocation,
+    };
+}
+/** Read the suite's MCP config: `mcp.json` or `.mcp.json`, else the winning manifest's inline `mcpServers`. */
+export async function discoverMcp(root, errors) {
+    for (const name of ['mcp.json', '.mcp.json']) {
+        const path = join(root, name);
+        if (!await isFile(path))
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(await readFile(path, 'utf8'));
+        }
+        catch (error) {
+            errors.push(`${name} unparsable: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+        const result = await validateMcpJson(root, raw, { strict: name === 'mcp.json' });
+        errors.push(...result.errors);
+        return result.config;
+    }
+    const inline = await declaredMcpServers(root);
+    if (inline === undefined)
+        return undefined;
+    const result = await validateMcpJson(root, { mcpServers: inline }, { strict: false });
+    errors.push(...result.errors);
+    return result.config;
+}
+/** Count surfaces for a suite; mcp counts only validated servers. */
+export async function countSurfaces(root, skills, mcp) {
+    let hooks = 0;
+    for (const relative of [join('hooks', 'hooks.json'), 'hooks.json']) {
+        hooks += await countHookEntries(join(root, relative));
+    }
+    const commands = (await listMdFiles(join(root, 'commands'))).length;
+    const agents = (await listMdFiles(join(root, 'agents'))).length;
+    const lsp = (await discoverLspEntries(root)).length;
+    return {
+        skills: skills.length,
+        mcp: mcp === undefined ? 0 : Object.keys(mcp.servers).length,
+        hooks,
+        commands,
+        agents,
+        lsp,
+    };
+}
+/** LSP definitions: `.claude-plugin/lsp/*.json` plus reverse-domain `lsp/` dirs. */
+export async function discoverLspEntries(root) {
+    const entries = [];
+    try {
+        for (const entry of await readdir(join(root, '.claude-plugin', 'lsp'))) {
+            if (entry.endsWith('.json'))
+                entries.push({ name: entry.slice(0, -5), path: join(root, '.claude-plugin', 'lsp', entry) });
+        }
+    }
+    catch {
+        // no .claude-plugin/lsp directory
+    }
+    try {
+        for (const entry of await readdir(root, { withFileTypes: true })) {
+            if (!entry.isDirectory() || !/^[a-z0-9-]+(\.[a-z0-9-]+){2,}$/.test(entry.name))
+                continue;
+            const lspDir = join(root, entry.name, 'lsp');
+            let names;
+            try {
+                names = await readdir(lspDir);
+            }
+            catch {
+                continue;
+            }
+            for (const name of names) {
+                entries.push({ name, path: join(lspDir, name) });
+            }
+        }
+    }
+    catch {
+        // unreadable root contributes no LSP entries
+    }
+    return entries;
+}
+async function countHookEntries(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        return 0;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== 'object' || parsed === null)
+            return 0;
+        const hooks = parsed['hooks'];
+        if (typeof hooks !== 'object' || hooks === null)
+            return 0;
+        return Object.values(hooks).reduce((total, entries) => total + (Array.isArray(entries) ? entries.length : 0), 0);
+    }
+    catch {
+        return 0;
+    }
+}
+/** File names under a suite's commands/ or agents/ directory. */
+export async function listMdFiles(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries.filter(name => name.endsWith('.md')).sort();
+}
+async function listChildDirs(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter(entry => entry.isDirectory() && !DOT_DIRS.has(entry.name) && !entry.name.startsWith('.'))
+        .map(entry => join(dir, entry.name));
+}
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/lib/discovery.js

@@ -0,0 +1,234 @@
+/**
+ * Suite discovery facade: maps a repository checkout (or a configured source
+ * list) onto normalized suites.
+ *
+ * Pipeline: the manifest layer (src/discovery/manifests.ts) detects which
+ * suite-manifest dialects a root carries and resolves names; the roots step
+ * decides where suites live (marketplace entries, a single root, container
+ * scans, or manifest-less skill collections); the surface layer
+ * (src/discovery/surfaces.ts) scans skills/commands/agents/hooks/lsp/mcp.
+ *
+ * The public API of this module is the discovery contract importers depend
+ * on: discoverSuitesInSource, discoverSourceList, listMdFiles,
+ * discoverLspEntries, and the new repoName for source-id derivation.
+ */
+import { readdir } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { expandHome, isDirectory, sanitizeId, sourcesDir } from './paths.js';
+import { declaredSkillsPath, detectManifest, marketplaceEntryDir, readManifest, readMarketplace, repoName, syntheticManifestName, } from './discovery/manifests.js';
+import { countSurfaces, discoverLspEntries, discoverMcp, discoverSkills, listMdFiles, } from './discovery/surfaces.js';
+export { repoName, listMdFiles, discoverLspEntries };
+const CONTAINER_DIRS = ['plugins', 'external_plugins', 'skills'];
+const DOT_DIRS = new Set(['.git', '.github', '.claude', '.cursor', '.kimi', '.plugin', '.sources', 'node_modules']);
+/** Discover every suite under one cloned source checkout. */
+export async function discoverSuitesInSource(checkoutDir, sourceId, dimension) {
+    const roots = await suiteRoots(checkoutDir);
+    const suites = [];
+    for (const root of roots) {
+        const suite = root.dir === undefined
+            ? remoteSuite(sourceId, dimension, root)
+            : await readSuite(root.dir, sourceId, dimension, root.hint);
+        if (suite !== undefined)
+            suites.push(suite);
+    }
+    return suites;
+}
+/**
+ * Resolve the suite roots of one checkout. A marketplace manifest is the
+ * authoritative list: local entries (relative paths, Codex `{source:
+ * 'local', path}`) surface when they carry a manifest or skills, container
+ * paths recurse into nested plugin dirs, and remote-URL entries become
+ * metadata-only remote suites. Manifest-bearing container dirs the
+ * marketplace did not list (e.g. official example plugins) are supplemented.
+ * Without a marketplace: a single-suite root, a recursive manifest/skill
+ * scan, or a manifest-less skill collection applies.
+ */
+async function suiteRoots(checkoutDir) {
+    const marketplace = await readMarketplace(checkoutDir);
+    if (marketplace !== undefined && marketplace.entries.length > 0) {
+        const roots = [];
+        const seen = new Set();
+        for (const entry of marketplace.entries) {
+            const hint = { name: entry.name, version: entry.version, description: entry.description };
+            const dir = marketplaceEntryDir(checkoutDir, entry);
+            if (dir === undefined) {
+                const remoteUrl = typeof entry.source === 'object' ? entry.source?.url : undefined;
+                // Dedupe by entry name, not URL: one remote repo can host several
+                // plugins that each appear as their own marketplace entry.
+                const entryName = typeof entry.name === 'string' && entry.name !== '' ? entry.name : remoteUrl;
+                if (remoteUrl !== undefined && entryName !== undefined && !seen.has(entryName)) {
+                    roots.push({ hint, remoteUrl });
+                    seen.add(entryName);
+                }
+                continue;
+            }
+            await collectRoot(dir, hint, roots, seen);
+        }
+        for (const container of CONTAINER_DIRS) {
+            const containerDir = join(checkoutDir, container);
+            if (!await isDirectory(containerDir))
+                continue;
+            for (const child of await listChildDirs(containerDir)) {
+                if (!seen.has(child) && await hasSuiteManifest(child))
+                    roots.push({ dir: child });
+            }
+        }
+        return roots;
+    }
+    if (await hasSuiteManifest(checkoutDir))
+        return [{ dir: checkoutDir }];
+    const found = [];
+    await collectRoot(checkoutDir, undefined, found, new Set());
+    if (found.length > 0)
+        return found;
+    // Manifest-less skill collection (the flat `<root>/<name>/SKILL.md` shape).
+    const collection = [];
+    for (const child of await listChildDirs(checkoutDir)) {
+        if (await hasSkillFiles(child))
+            collection.push({ dir: child });
+    }
+    return collection;
+}
+/** Collect one root, recursing through container dirs (nested `plugins/`
+ *  bundles) up to four levels so Codex runtime layouts
+ *  (`plugins/<bundle>/plugins/<name>`) are reached. */
+async function collectRoot(dir, hint, out, seen, depth = 0) {
+    if (depth > 4 || seen.has(dir))
+        return;
+    if (await hasSuiteManifest(dir) || await hasSkillFiles(dir)) {
+        out.push({ dir, hint });
+        seen.add(dir);
+        return;
+    }
+    for (const child of await listChildDirs(dir)) {
+        await collectRoot(child, hint, out, seen, depth + 1);
+    }
+}
+/** Whether a directory carries any known suite manifest. */
+async function hasSuiteManifest(dir) {
+    return (await detectManifest(dir)) !== undefined;
+}
+/** Whether a directory carries skill files in the flat or bundled shape. */
+async function hasSkillFiles(dir) {
+    if (await isFile(join(dir, 'SKILL.md')))
+        return true;
+    const skillsDir = join(dir, 'skills');
+    if (!await isDirectory(skillsDir))
+        return false;
+    for (const child of await listChildDirs(skillsDir)) {
+        if (await isFile(join(child, 'SKILL.md')))
+            return true;
+    }
+    return false;
+}
+async function listChildDirs(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter(entry => entry.isDirectory() && !DOT_DIRS.has(entry.name) && !entry.name.startsWith('.'))
+        .map(entry => join(dir, entry.name));
+}
+/** Read one suite root into the normalized shape, or `undefined` when no manifest parses. */
+async function readSuite(root, sourceId, dimension, hint) {
+    const errors = [];
+    const manifest = await readManifest(root, errors, hint) ?? await syntheticManifest(root);
+    if (manifest === undefined)
+        return undefined;
+    const declared = await declaredSkillsPath(root);
+    const skills = await discoverSkills(root, errors, declared);
+    const mcp = await discoverMcp(root, errors);
+    const surfaces = await countSurfaces(root, skills, mcp);
+    return {
+        sourceId,
+        id: manifest.id,
+        root,
+        manifest,
+        skills,
+        ...mcp === undefined ? {} : { mcp },
+        surfaces,
+        dimension,
+        enabled: false,
+        errors,
+    };
+}
+/** Metadata-only suite for a marketplace entry whose content lives in a
+ *  remote repository that is not part of this clone. */
+function remoteSuite(sourceId, dimension, root) {
+    const name = root.hint?.name ?? 'remote-plugin';
+    return {
+        sourceId,
+        id: sanitizeId(name),
+        root: '',
+        manifest: {
+            layout: 'remote',
+            path: '',
+            id: sanitizeId(name),
+            name,
+            version: root.hint?.version,
+            description: root.hint?.description,
+        },
+        skills: [],
+        surfaces: { skills: 0, mcp: 0, hooks: 0, commands: 0, agents: 0, lsp: 0 },
+        dimension,
+        enabled: false,
+        remote: { url: root.remoteUrl ?? '' },
+        errors: [],
+    };
+}
+/** Manifest-less directories still produce a synthetic suite identity. */
+async function syntheticManifest(root) {
+    if (!await hasSkillFiles(root))
+        return undefined;
+    const name = syntheticManifestName(root);
+    return {
+        layout: 'skill-collection',
+        path: join(root, 'SKILL.md'),
+        id: sanitizeId(name),
+        name,
+    };
+}
+async function isFile(path) {
+    try {
+        return (await (await import('node:fs/promises')).stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether a suite root path lies outside the checkout (defense for malformed marketplace sources). */
+export function isOutside(root, candidate) {
+    return isAbsolute(candidate) ? !candidate.startsWith(root) : false;
+}
+/**
+ * Discover every suite of one dimension's configured sources, plus manual
+ * checkouts present under the dimension's `.sources/` that no source entry
+ * names. Local sources read their directory directly; git sources read
+ * their clone; a missing checkout contributes nothing.
+ */
+export async function discoverSourceList(sources, dimension, dimensionRoot) {
+    const checkoutRoot = sourcesDir(dimensionRoot);
+    const bySource = new Map();
+    const listed = new Set(sources.map(source => source.id));
+    try {
+        for (const entry of await readdir(checkoutRoot, { withFileTypes: true })) {
+            if (!entry.isDirectory() || entry.name.startsWith('.') || listed.has(entry.name))
+                continue;
+            bySource.set(entry.name, await discoverSuitesInSource(join(checkoutRoot, entry.name), entry.name, dimension));
+        }
+    }
+    catch {
+        // a missing checkout root simply has no manual checkouts
+    }
+    for (const source of sources) {
+        const checkout = source.local === true ? expandHome(source.url) : join(checkoutRoot, source.id);
+        if (!await isDirectory(checkout))
+            continue;
+        bySource.set(source.id, await discoverSuitesInSource(checkout, source.id, dimension));
+    }
+    return [...bySource.values()].flat();
+}