dsh-agent-plugins-market 0.6.0 → 0.6.2

package/lib/runtime/user-panels.js

@@ -0,0 +1,176 @@
+/**
+ * User panel storage: the persistence layer behind the skills / commands /
+ * agent-personas panels. Each surface owns one directory of Markdown files
+ * under `<userRoot>/user/<kind>/`, so user-authored entries survive restarts,
+ * are trivially hand-editable, and stay outside suite checkouts.
+ *
+ * Skills entries follow the SKILL.md frontmatter grammar (`name`,
+ * `description`, optional `whenToUse`, invocation controls) plus a
+ * `disabled: true` panel control; commands follow Claude Code command
+ * frontmatter (`description`, optional `argument-hint`, `disabled`); agent
+ * personas follow Claude Code agents frontmatter (`name`, `description`,
+ * optional `whenToUse`, `tools`, `model`, `disabled`).
+ * @module runtime/user-panels
+ */
+import { join } from 'node:path';
+import { deleteEntryFile, entryExists, listEntryFiles, readEntryFile, USER_ENTRY_NAME, userEntryDir, writeEntryFile } from './user-store.js';
+/** The skill-source label user-panel entries carry into the skill registry. */
+export const USER_PANEL_SKILL_SOURCE = 'user-panel';
+/** Ranks sit behind every shipped root so real files always win a name clash. */
+const USER_PANEL_RANK = 600;
+/** Throwing CRUD over one panel directory, shared by the three panels. */
+export class UserPanelStore {
+    dataRoot;
+    kind;
+    extraNameCheck;
+    constructor(dataRoot, kind, 
+    /** Extra name grammar for this panel (runs after USER_ENTRY_NAME). */
+    extraNameCheck = () => true) {
+        this.dataRoot = dataRoot;
+        this.kind = kind;
+        this.extraNameCheck = extraNameCheck;
+    }
+    /** The panel's directory under the data root. */
+    dirPath() {
+        return userEntryDir(this.dataRoot, this.kind);
+    }
+    /** The plugin data root the panel lives under. */
+    root() {
+        return this.dataRoot;
+    }
+    get dir() {
+        return this.dirPath();
+    }
+    /** Every entry, sorted by name; strict snapshots propagate temporary I/O failures. */
+    async list(strict = false) {
+        const files = await listEntryFiles(this.dir, strict);
+        return files.map(file => this.serialize(file));
+    }
+    /** One entry's full record, including the raw file text. */
+    async get(name) {
+        if (!USER_ENTRY_NAME.test(name))
+            return undefined;
+        const file = await readEntryFile(join(this.dir, `${name}.md`), name);
+        if (file === undefined)
+            return undefined;
+        return this.serialize(file);
+    }
+    /**
+     * Project one parsed file onto the wire shape. The description prefers the
+     * strict frontmatter parse (multi-line YAML like `description: |` survives
+     * intact there) and falls back to the shallow line record.
+     */
+    serialize(file) {
+        const strictDescription = typeof file.description === 'string' && file.description !== '' ? file.description : undefined;
+        const shallowDescription = typeof file.meta['description'] === 'string' && file.meta['description'] !== '' ? file.meta['description'] : '';
+        return {
+            name: file.fallbackName,
+            description: strictDescription ?? shallowDescription,
+            disabled: file.meta['disabled'] === true,
+            metadata: file.meta,
+            path: file.file,
+            content: file.body,
+            rawText: file.text,
+            origin: 'user'
+        };
+    }
+    /** Create an entry; refuses an occupied name. */
+    async create(name, text) {
+        if (!USER_ENTRY_NAME.test(name) || !this.extraNameCheck(name))
+            throw new Error(`invalid name "${name}" — use lowercase letters, digits, and dashes, starting with a letter or digit`);
+        if (await entryExists(this.dir, name))
+            throw new Error(`an entry named "${name}" already exists`);
+        await writeEntryFile(this.dir, name, text);
+        const created = await this.get(name);
+        if (created === undefined)
+            throw new Error(`entry "${name}" vanished after write`);
+        return created;
+    }
+    /** Replace one entry's file content wholesale. */
+    async update(name, text) {
+        if (!USER_ENTRY_NAME.test(name) || !this.extraNameCheck(name))
+            throw new Error(`invalid entry name "${name}"`);
+        if (!(await entryExists(this.dir, name)))
+            throw new Error(`no entry named "${name}"`);
+        await writeEntryFile(this.dir, name, text);
+    }
+    /** Delete one entry; a missing file is a no-op (idempotent delete). */
+    async remove(name) {
+        if (!USER_ENTRY_NAME.test(name))
+            throw new Error(`invalid entry name "${name}"`);
+        await deleteEntryFile(this.dir, name);
+    }
+}
+/** Locate the three stores; constructed once per plugin activation. */
+export function createUserPanelStores(dataRoot) {
+    return {
+        skills: new UserPanelStore(dataRoot, 'skills', isUserSkillEntryName),
+        commands: new UserPanelStore(dataRoot, 'commands'),
+        agents: new UserPanelStore(dataRoot, 'agents', isUserSkillEntryName)
+    };
+}
+/**
+ * The skills/agents panels accept only harness skill-grammar names
+ * (`[a-z0-9-]`, no underscores): a candidate name reaching the skill
+ * registry's `get()` with an invalid name is dropped there, and several
+ * consumers validate strictly, so `_`-named entries would be dead weight.
+ * Commands keep the looser command grammar (`_` allowed).
+ */
+export function isUserSkillEntryName(name) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+}
+/**
+ * Skill provider over user skills only. Agent definitions belong to the
+ * subagent catalog and never become skill candidates or slash entries.
+ */
+export class UserPanelSkillProvider {
+    skills;
+    t;
+    name = 'user-panel';
+    constructor(skills, t) {
+        this.skills = skills;
+        this.t = t;
+    }
+    async list(_options) {
+        const candidates = [];
+        const skills = await this.skills.list();
+        for (const entry of skills) {
+            if (entry.disabled || !isUserSkillEntryName(entry.name))
+                continue;
+            candidates.push({
+                name: entry.name,
+                description: this.t('userSkillDescription', { description: entry.description === '' ? entry.name : entry.description }),
+                ...(typeof entry.metadata['whenToUse'] === 'string' && entry.metadata['whenToUse'] !== '' ? { whenToUse: entry.metadata['whenToUse'] } : {}),
+                invocation: {
+                    modelInvocable: entry.metadata['disable-model-invocation'] !== true,
+                    userInvocable: entry.metadata['user-invocable'] !== false
+                },
+                source: USER_PANEL_SKILL_SOURCE,
+                provider: this.name,
+                rank: USER_PANEL_RANK,
+                locator: { name: entry.name },
+                path: entry.path,
+                resourceBase: { kind: 'directory', path: this.skills.dirPath() }
+            });
+        }
+        return candidates;
+    }
+    async get(candidate, _options) {
+        const locator = candidate.locator;
+        const store = this.skills;
+        const entry = await store.get(locator.name);
+        if (entry === undefined || entry.disabled)
+            return undefined;
+        return {
+            name: candidate.name,
+            description: candidate.description,
+            ...(typeof entry.metadata['whenToUse'] === 'string' && entry.metadata['whenToUse'] !== '' ? { whenToUse: entry.metadata['whenToUse'] } : {}),
+            invocation: candidate.invocation,
+            source: candidate.source,
+            provider: this.name,
+            resourceBase: { kind: 'directory', path: store.dirPath() },
+            path: entry.path,
+            content: entry.content
+        };
+    }
+}

package/lib/runtime/user-store.js

@@ -0,0 +1,142 @@
+/**
+ * Shared persistence primitives for the market's user-authored panels:
+ * skills, commands, and agent personas. Each panel owns one directory of
+ * Markdown files under the plugin data root, parsed with the same frontmatter
+ * rules the catalog uses, so user entries look exactly like suite entries to
+ * the runtime mounts.
+ * @module runtime/user-store
+ */
+import { mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseDocument, stringify } from 'yaml';
+import { parseSkillFrontmatter, stripFrontmatter } from '../catalog/skills-parse.js';
+/** Where user panel entries persist: `<userRoot>/user/<kind>/`. */
+export function userEntryDir(dataRoot, kind) {
+    return join(dataRoot, 'user', kind);
+}
+/** `[a-z][a-z0-9_-]*` — the grammar every panel entry name must satisfy. */
+export const USER_ENTRY_NAME = /^[a-z][a-z0-9_-]*$/;
+/** The enablement frontmatter key shared by skills and commands. */
+export const DISABLED_KEY = 'disabled';
+/** Parse full YAML metadata without flattening arrays, mappings, or multiline strings. */
+export function parseFrontmatterRecord(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (match === null) {
+        if (/^---(?:\r?\n|$)/.test(text))
+            throw new Error('Invalid frontmatter: missing closing delimiter');
+        return {};
+    }
+    const doc = parseDocument(match[1]);
+    if (doc.errors.length > 0)
+        throw new Error(`Invalid frontmatter: ${doc.errors[0].message}`);
+    const value = doc.toJS({ maxAliasCount: 100 });
+    if (value === null)
+        return {};
+    if (typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Frontmatter must be a mapping');
+    return value;
+}
+/** Read one entry; strict runtime snapshots throw on I/O errors other than a vanished file. */
+export async function readEntryFile(file, fallbackName, strict = false) {
+    if (fallbackName !== '' && !USER_ENTRY_NAME.test(fallbackName))
+        return undefined;
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (strict && error.code !== 'ENOENT')
+            throw error;
+        return undefined;
+    }
+    let meta;
+    try {
+        meta = parseFrontmatterRecord(text);
+    }
+    catch (error) {
+        meta = { disabled: true, validationError: String(error) };
+    }
+    const parsed = parseSkillFrontmatter(text, fallbackName);
+    const name = typeof parsed === 'string' ? fallbackName : typeof parsed.name === 'string' && parsed.name !== '' ? parsed.name : fallbackName;
+    return {
+        fallbackName,
+        name,
+        file,
+        text,
+        body: stripFrontmatter(text),
+        meta,
+        ...(typeof parsed === 'string' ? {} : parsed)
+    };
+}
+/** List `.md` entries; strict runtime snapshots propagate I/O errors instead of publishing partial inventories. */
+export async function listEntryFiles(dir, strict = false) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (strict && error.code !== 'ENOENT')
+            throw error;
+        return [];
+    }
+    const found = [];
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith('.md'))
+            continue;
+        const file = join(dir, entry);
+        try {
+            const info = await stat(file);
+            if (!info.isFile())
+                continue;
+        }
+        catch (error) {
+            if (strict && error.code !== 'ENOENT')
+                throw error;
+            continue;
+        }
+        const parsed = await readEntryFile(file, entry.slice(0, -3), strict);
+        if (parsed !== undefined)
+            found.push(parsed);
+    }
+    return found;
+}
+/** Write one panel entry; the name becomes `<name>.md`. */
+export async function writeEntryFile(dir, name, text) {
+    assertEntryName(name);
+    parseFrontmatterRecord(text);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, `${name}.md`), text, 'utf8');
+}
+/**
+ * Enforce the entry-name grammar at every filesystem choke point. The name
+ * is interpolated into `join(dir, name + '.md')`, so an unchecked name with
+ * separators or `..` could address any `.md` file (or directory) on disk —
+ * read, write, and delete all go through this guard.
+ */
+function assertEntryName(name) {
+    if (!USER_ENTRY_NAME.test(name))
+        throw new Error(`invalid entry name "${name}" — use lowercase letters, digits, dashes, or underscores, starting with a letter`);
+}
+/** Delete one panel entry file; missing files resolve silently. */
+export async function deleteEntryFile(dir, name) {
+    assertEntryName(name);
+    await rm(join(dir, `${name}.md`), { force: true });
+}
+/** Whether an entry file with that name already exists. */
+export async function entryExists(dir, name) {
+    if (!USER_ENTRY_NAME.test(name))
+        return false;
+    try {
+        await stat(join(dir, `${name}.md`));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Serialize a frontmatter block from a shallow record (deterministic key order). */
+export function serializeFrontmatter(meta) {
+    if (Object.keys(meta).length === 0)
+        return '';
+    return `---\n${stringify(meta, { sortMapEntries: true })}---\n`;
+}

package/lib/types/application/catalog.d.ts

@@ -7,7 +7,7 @@ import { type HostMcpClientProbe, type McpBackend } from '../runtime/mcp-backend
 import { type DownloadRegionSetting, type EffectiveRegion } from '../runtime/regions.js';
 import type { McpStatusPayload } from '../contracts/mcp-status.js';
 import type { LspStatusPayload } from '../contracts/lsp-status.js';
-import type { OverviewPayload, SkillContent, SuiteDetail } from '../contracts/market.js';
+import type { OverviewPayload, ServerConfigPayload, SkillContent, SuiteDetail } from '../contracts/market.js';
 import { type SourceKind, type SourceRef, type Suite, type SuiteDimension, type SuiteSurfaceKey } from '../model/types.js';
 /**
  * Git network tuning, plumbed from the host config to every remote-touching
@@ -70,12 +70,13 @@ export declare class Catalog {
      * discovery (cheap mapping) instead of re-walking every checkout — a full
      * rescan of a 2,500-suite catalog costs ~1s and UI mutations happen in
      * bursts. Content-changing mutations (add / update / remove / adopt /
-     * refresh / acquire) set {@link scanCacheDirty}, which bypasses the cache
-     * until the next scan; the TTL bounds staleness for in-place working-tree
+     * refresh / acquire) clear every cached discovery generation; the TTL
+     * bounds staleness for in-place working-tree
      * edits of local sources.
      */
     private readonly scanCache;
-    private scanCacheDirty;
+    private scanGeneration;
+    private readonly scanPromises;
     private static readonly SCAN_CACHE_TTL_MS;
     private static readonly SCAN_CACHE_MAX_ENTRIES;
     /**
@@ -107,6 +108,9 @@ export declare class Catalog {
     private mcpBackendWriter;
     /** Download-region source (the host settings namespace scope). */
     private downloadRegionProvider;
+    private scanProjectLayouts;
+    /** Apply the host's project-layout switch and invalidate every project snapshot. */
+    setScanProjectLayouts(enabled: boolean): Promise<void>;
     constructor(options: CatalogOptions);
     /** Install the host tool snapshot provider used by the MCP status surface. */
     setMcpToolSnapshotProvider(provider: () => readonly McpToolSnapshot[]): void;
@@ -137,12 +141,22 @@ export declare class Catalog {
     subscribe(listener: () => void): () => void;
     /** Build the flat MCP service inventory for the status surface. */
     mcpStatus(): Promise<McpStatusPayload>;
+    /** Persist a user-owned MCP service and reconcile its bridge mount. */
+    addMcpServer(name: string, server: unknown): Promise<void>;
+    /** Read effective service configuration without exposing credential literals. */
+    serverConfig(kind: 'mcp' | 'lsp', id: string): Promise<ServerConfigPayload>;
+    private resolveServerConfig;
+    /** Validate a complete replacement before writing; plugin checkouts remain untouched. */
+    saveServerConfig(kind: 'mcp' | 'lsp', id: string, config: unknown): Promise<void>;
     /** The LSP status surface: declared servers merged with mount diagnostics. */
     lspStatus(): Promise<LspStatusPayload>;
     /** The user's direct LSP server table (normalized specs). */
     lspServers(): Promise<Record<string, import('../model/types.js').LspServerSpec>>;
+    /** Create one direct LSP declaration without replacing other user servers. */
+    addLspServer(name: string, config: unknown): Promise<void>;
     /** Validate and persist the user's direct LSP server table. */
     setLspServers(raw: unknown): Promise<Record<string, import('../model/types.js').LspServerSpec>>;
+    setLspServerEnabled(id: string, enabled: boolean): Promise<void>;
     /** One suite's persisted MCP overrides, addressed by qualified suite id. */
     mcpOverrides(sourceId: string, suiteId: string): Promise<McpSuiteOverrides>;
     /**
@@ -183,8 +197,8 @@ export declare class Catalog {
     setMcpBackendWriter(writer: (backend: McpBackend) => Promise<void>): void;
     /** Install the download-region source (the host settings namespace scope). */
     setDownloadRegionProvider(provider: () => Promise<DownloadRegionSetting>): void;
-    /** All persisted MCP overrides keyed by qualified suite id (mount-time provider). */
-    allMcpOverrides(): Promise<Map<string, McpSuiteOverrides>>;
+    /** MCP overrides for a supplied runtime selection, or the full market catalog when omitted. */
+    allMcpOverrides(suites?: readonly Suite[]): Promise<Map<string, McpSuiteOverrides>>;
     /** Load persisted user state once at plugin activation. */
     load(): Promise<void>;
     get sources(): SourceRef[];
@@ -201,7 +215,7 @@ export declare class Catalog {
     skillContent(sourceId: string, suiteId: string, skillName: string): Promise<SkillContent>;
     /** The full market overview from one user snapshot. */
     overview(): Promise<OverviewPayload>;
-    /** Enabled user-dimension suites from one user snapshot. */
+    /** Runtime discovery scans only sources containing an enabled install. No acquisition or network access. */
     enabledUserSuites(): Promise<Suite[]>;
     /** Enabled user- and project-dimension suites for a workspace cwd. */
     enabledSuitesForCwd(cwd: string): Promise<{
@@ -271,8 +285,16 @@ export declare class Catalog {
         kind?: SourceKind;
         sha256?: string;
     }): Promise<void>;
-    /** Remove a source, its install entries, and its managed checkout. */
-    removeSource(sourceId: string): Promise<void>;
+    /**
+     * Remove a source and its install entries. `deleteCheckout` (the UI's
+     * "also delete the managed market directory" option) physically removes the
+     * `.sources/<id>` checkout — including an adopted one, since a directory
+     * under `.sources` is manager-owned storage. A `local` source whose URL
+     * points outside `.sources` is registration-only: its directory is never
+     * touched. Deleting the checkout is what keeps a removed source from
+     * reappearing as an unmanaged entry.
+     */
+    removeSource(sourceId: string, deleteCheckout?: boolean): Promise<void>;
     /** Refresh one source checkout, or every source when sourceId is omitted. */
     refreshSource(sourceId?: string): Promise<void>;
     /** Install a suite from a source and enable it. The client confirms the
@@ -287,6 +309,13 @@ export declare class Catalog {
     setSurface(sourceId: string, suiteId: string, surface: SuiteSurfaceKey, enabled: boolean): Promise<void>;
     /** Append config-seeded sources missing from user state and persist them. */
     mergeSources(sources: SourceRef[]): Promise<void>;
+    /**
+     * Panel changed hook: the HTTP layer notifies after a user-panel mutation
+     * (skills / commands / agent personas). Catalog state is untouched — this
+     * only runs the change pipeline so the runtime remounts commands and the
+     * skill providers re-read their catalogs.
+     */
+    notifyPanelsChanged(): Promise<void>;
     private setInstalled;
     /**
      * Acquire one source's content by kind: clone (git), download+extract
@@ -299,6 +328,7 @@ export declare class Catalog {
     private sourceCheckoutPath;
     private buildSnapshot;
     private invalidateSnapshot;
+    private invalidateScans;
     /**
      * Invalidate snapshots and run the change pipeline. `keepScanCache` marks
      * state-only mutations (install, enable, surface toggles, MCP overrides)

package/lib/types/application/panel-resources.d.ts

@@ -0,0 +1,13 @@
+import type { UserPanelEntryWire, UserPanelKind } from '../contracts/market.js';
+import type { UserPanelStore } from '../runtime/user-panels.js';
+import type { Catalog } from './catalog.js';
+/** The routes consume this structural surface, also implemented by user-only stores in tests. */
+export interface PanelResourceStore {
+    /** Strict runtime reads propagate I/O failures so catalogs cannot publish partial replacements. */
+    list(strict?: boolean): Promise<UserPanelEntryWire[]>;
+    get(id: string): Promise<UserPanelEntryWire | undefined>;
+    create(name: string, text: string): Promise<UserPanelEntryWire>;
+    update(id: string, text: string): Promise<void>;
+    remove(id: string): Promise<void>;
+}
+export declare function createPanelResources(catalog: Catalog, users: Record<UserPanelKind, UserPanelStore>): Record<UserPanelKind, PanelResourceStore>;

package/lib/types/application/project-agent-roles.d.ts

@@ -0,0 +1,3 @@
+import { type AgentRoleEntry } from '../runtime/agent-role-router.js';
+import type { Catalog } from './catalog.js';
+export declare function projectAgentRoles(catalog: Catalog, parent: unknown): Promise<AgentRoleEntry[]>;

package/lib/types/application/queries.d.ts

@@ -5,8 +5,10 @@ import type { OverviewPayload, SkillContent, SourceProgress, SuiteDetail } from
 import type { SourceRef, SuiteSurfaceKey } from '../model/types.js';
 import type { McpServerOverride, McpSuiteOverrides } from '../runtime/mcp-overrides.js';
 import type { HostMcpClientProbe, McpBackend } from '../runtime/mcp-backend.js';
+import type { ServerConfigPayload } from '../contracts/market.js';
 /** Read-only market operations required by HTTP routes. */
 export interface MarketQueries {
+    serverConfig(kind: 'mcp' | 'lsp', id: string): Promise<ServerConfigPayload>;
     readonly sources: SourceRef[];
     overview(): Promise<OverviewPayload>;
     mcpStatus(): Promise<McpStatusPayload>;
@@ -19,6 +21,9 @@ export interface MarketQueries {
 }
 /** Mutating market operations required by HTTP routes. */
 export interface MarketMutations {
+    saveServerConfig(kind: 'mcp' | 'lsp', id: string, config: unknown): Promise<void>;
+    addMcpServer(name: string, server: unknown): Promise<void>;
+    addLspServer(name: string, config: unknown): Promise<void>;
     addSource(input: {
         url: string;
         branch?: string;
@@ -33,7 +38,11 @@ export interface MarketMutations {
         kind?: 'git' | 'local' | 'archive';
         sha256?: string;
     }): Promise<void>;
-    removeSource(sourceId: string): Promise<void>;
+    /**
+     * Remove a source registration; `deleteCheckout` also physically deletes
+     * its managed `.sources/<id>` checkout. External local paths are never deleted.
+     */
+    removeSource(sourceId: string, deleteCheckout?: boolean): Promise<void>;
     /** Register an unmanaged `.sources/` checkout in place (manual-clone repair). */
     adoptSource(id: string): Promise<SourceRef>;
     refreshSource(sourceId?: string): Promise<void>;
@@ -44,6 +53,7 @@ export interface MarketMutations {
     setMcpOverride(sourceId: string, suiteId: string, serverKey: string, override: McpServerOverride | null): Promise<void>;
     /** Validate and persist the user's direct LSP server table. */
     setLspServers(raw: unknown): Promise<Record<string, import('../model/types.js').LspServerSpec>>;
+    setLspServerEnabled(id: string, enabled: boolean): Promise<void>;
     /** Re-run the MCP reconcile pass: retries failed mounts and clears residual tools. */
     retryMounts(): Promise<void>;
     reauthorizeMcpServer(serverName: string): Promise<void>;
@@ -59,6 +69,12 @@ export interface MarketMutations {
     }>;
     /** Switch the MCP mount backend and remount every suite server through it. */
     setMcpBackend(backend: McpBackend): Promise<void>;
+    /**
+     * Panel change hook: the HTTP layer notifies after a user-panel mutation
+     * (skills / commands / agent personas) so the runtime remounts commands
+     * and the skill providers re-read their catalogs.
+     */
+    notifyPanelsChanged(): Promise<void>;
 }
 /** Complete application surface required by the HTTP routes. */
 export type MarketService = MarketQueries & MarketMutations;

package/lib/types/catalog/codex-mcp.d.ts

@@ -0,0 +1,4 @@
+/** Codex TOML MCP tables normalize into the existing transport and credential contracts. */
+import type { McpServer } from '../model/types.js';
+/** Unknown or malformed server options reject that server; other servers stay independently usable. */
+export declare function normalizeCodexMcp(raw: Record<string, unknown>, errors: string[]): Record<string, McpServer>;

package/lib/types/catalog/component-files.d.ts

@@ -0,0 +1,17 @@
+import type { SuiteMarkdownResource } from '../model/types.js';
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Reject both lexical and symlink escapes. Optional defaults may be absent without a diagnostic. */
+export declare function componentPath(root: string, value: string, errors: string[], required?: boolean): Promise<string | undefined>;
+/** Commands and agents may declare one file, several files, or recursive directories. */
+export declare function discoverMarkdownResources(root: string, component: 'commands' | 'agents', declaration: unknown, manifestPath: string, errors: string[], extensions?: readonly string[]): Promise<SuiteMarkdownResource[]>;
+export interface ComponentDocument {
+    path?: string;
+    value: Record<string, unknown>;
+}
+/** A malformed declared file invalidates that configuration surface instead of falling back. */
+export declare function componentDocuments(root: string, declaration: unknown, errors: string[], allowDirectory?: boolean): Promise<ComponentDocument[] | undefined>;
+export declare function firstComponentFile(root: string, candidates: readonly string[]): Promise<string | undefined>;
+/** Legacy/native suites without catalog resource lists keep their conventional directory behavior. */
+export declare function defaultMarkdownResources(root: string, component: 'agents' | 'commands'): Promise<SuiteMarkdownResource[]>;
+export declare function resourceText(resource: SuiteMarkdownResource): Promise<string>;
+export declare function resourceCommandName(name: string): string;

package/lib/types/catalog/manifests.d.ts

@@ -1,5 +1,6 @@
-import type { SuiteManifest } from '../model/types.js';
-export type ManifestKind = 'agent-plugin-v1' | 'universal' | 'claude-code' | 'cursor' | 'kimi' | 'codex';
+import type { SuiteManifest, SuiteComponents } from '../model/types.js';
+import { type ManifestKind } from '../model/layouts.js';
+export type { ManifestKind } from '../model/layouts.js';
 /** One manifest candidate: its file path and the dialect it selects. */
 export interface ManifestCandidate {
     kind: ManifestKind;
@@ -11,17 +12,20 @@ export declare function detectManifest(dir: string): Promise<ManifestCandidate |
 export declare function hasSuiteManifest(dir: string): Promise<boolean>;
 /** Fallback suite identity for manifest-less skill collections. */
 export declare function syntheticManifestName(root: string): string;
+export declare function componentDeclarations(record: object): SuiteComponents;
 /**
  * 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 declare function readManifest(root: string, errors: string[], hint: {
+export declare function readManifest(root: string, errors: string[], hint: ({
     name?: string;
     version?: string;
     description?: string;
-} | undefined): Promise<SuiteManifest | undefined>;
-export interface MarketplaceEntry {
+} & SuiteComponents) | undefined): Promise<SuiteManifest | undefined>;
+export interface MarketplaceEntry extends SuiteComponents {
+    layout?: ManifestKind;
+    strict?: boolean;
     name?: string;
     version?: string;
     description?: string;
@@ -36,6 +40,7 @@ export interface MarketplaceEntry {
     };
 }
 export interface Marketplace {
+    pluginRoot?: string;
     name?: string;
     entries: MarketplaceEntry[];
 }
@@ -45,11 +50,11 @@ export interface ReadMarketplaceResult extends Marketplace {
 }
 /**
  * Read every marketplace manifest the checkout carries, in dialect
- * precedence order (Claude Code before Codex). Both dialects can coexist
- * (e.g. a repo shipping one marketplace per agent); callers decide which
- * dialect's entries win, so no dialect is silently shadowed.
+ * precedence order shared with suite manifests, then the shared root catalog.
+ * The scan strategy selects the first catalog that produces suites; an empty
+ * or invalid catalog allows the next candidate to be tried.
  */
-export declare function readMarketplaces(checkoutDir: string): Promise<ReadMarketplaceResult[]>;
+export declare function readMarketplaces(checkoutDir: string, errors?: string[]): Promise<ReadMarketplaceResult[]>;
 /** Read the highest-precedence marketplace manifest, or undefined when absent. */
 export declare function readMarketplace(checkoutDir: string): Promise<Marketplace | undefined>;
 /** Resolve one marketplace entry to a local checkout-relative directory, or

package/lib/types/catalog/native-project.d.ts

@@ -1,14 +1,11 @@
 import type { Suite, SuiteDimension } from '../model/types.js';
+import { type ProjectLayout } from '../model/layouts.js';
 /**
  * Project-local directory conventions, in precedence order. Each entry maps
  * one agent convention onto the content subdirectories it owns.
  */
 export declare const NATIVE_PROJECT_DIRS: readonly NativeProjectDir[];
-export interface NativeProjectDir {
-    dirName: string;
-    label: string;
-    subdirs: readonly string[];
-}
+export type NativeProjectDir = ProjectLayout;
 /**
  * Discover native project-layout suites under a project root. Each
  * convention directory that carries content becomes one synthetic suite;

package/lib/types/catalog/paths.d.ts

@@ -7,14 +7,14 @@ export declare const STATE_FILE_NAME = "state.json";
 export declare function expandHome(path: string): string;
 /** Resolve the harness home (`$DSH_HOME` or `~/.dsh`). */
 export declare function resolveDshHome(): string;
-/** Resolve the user-dimension suite root. */
-export declare function resolveUserRoot(configUserRoot?: string): string;
+/** Resolve the canonical user-dimension root. Legacy overrides are migration inputs only. */
+export declare function resolveUserRoot(_configUserRoot?: string): string;
 /**
  * Resolve the suite data root hosting `${PLUGIN_DATA}` directories and the
  * MCP overrides. Defaults under the user root so the whole plugin persists
- * into one directory; an explicit `dataRoot` config still wins.
+ * into one directory. Legacy overrides are migration inputs only.
  */
-export declare function resolveDataRoot(configDataRoot?: string, configUserRoot?: string): string;
+export declare function resolveDataRoot(_configDataRoot?: string, _configUserRoot?: string): string;
 /** Resolve a project root from a workspace cwd: nearest ancestor with `.git`. */
 export declare function findProjectRoot(cwd: string): Promise<string>;
 /** Resolve the project-dimension suite root for a workspace cwd. */

package/lib/types/catalog/project-config.d.ts

@@ -0,0 +1,6 @@
+import type { McpSuiteConfig } from '../model/types.js';
+import type { ProjectMcpFormat } from '../model/layouts.js';
+/** Later files override earlier keys; a malformed layer invalidates the whole layout's table. */
+export declare function discoverProjectMcp(projectRoot: string, files: readonly string[], errors: string[], format?: ProjectMcpFormat): Promise<McpSuiteConfig | undefined>;
+/** Missing is undefined; malformed/unreadable is null and carries a diagnostic. */
+export declare function readProjectDocument(projectRoot: string, file: string, errors: string[], format?: 'JSON' | 'TOML'): Promise<Record<string, unknown> | undefined | null>;

package/lib/types/catalog/project-hooks.d.ts

@@ -0,0 +1,10 @@
+/** Normalize native Claude-shaped command hooks for the existing host execution bridge. */
+import type { ProjectHooks } from '../model/types.js';
+import type { ProjectHookFormat } from '../model/layouts.js';
+/** Merge settings layers additively, deduplicating identical event/matcher/command triples. */
+export declare function discoverProjectHooks(projectRoot: string, files: readonly string[], errors: string[], format?: ProjectHookFormat): Promise<ProjectHooks | undefined>;
+/** Pure validation shared by native settings and plugin file/inline declarations. */
+export declare function normalizeHookDocuments(projectRoot: string, documents: Array<{
+    file: string;
+    settings: Record<string, unknown>;
+}>, errors: string[], format?: ProjectHookFormat): ProjectHooks | undefined;