dsh-agent-plugins-market 0.6.2 → 0.7.1

package/lib/types/application/mcp-service.d.ts

@@ -0,0 +1,77 @@
+import type { McpStatusPayload } from '../contracts/mcp-status.js';
+import type { ServerConfigPayload } from '../contracts/market.js';
+import type { Suite } from '../model/types.js';
+import { type McpBackend } from '../runtime/mcp-backend.js';
+import type { McpMountDiagnostic } from '../runtime/mcp-mounts.js';
+import { type McpServerOverride, type McpSuiteOverrides } from '../runtime/mcp-overrides.js';
+import type { CatalogContext } from './catalog-context.js';
+import type { CatalogPorts, McpBackendInfo } from './ports.js';
+import type { SourceStore } from './source-store.js';
+export declare class McpService {
+    private readonly context;
+    private readonly ports;
+    private readonly sources;
+    /** Latest MCP mount diagnostics (suiteId -> reasons), fed by host reconcile. */
+    diagnostics: McpMountDiagnostic[];
+    constructor(context: CatalogContext, ports: CatalogPorts, sources: SourceStore);
+    /** Build the flat MCP service inventory for the status surface. */
+    status(): Promise<McpStatusPayload>;
+    /** Persist a user-owned MCP service and reconcile its bridge mount. */
+    addServer(name: string, server: unknown): Promise<void>;
+    /** Read effective service configuration without exposing credential literals. */
+    serverConfig(kind: 'mcp' | 'lsp', id: string): Promise<ServerConfigPayload>;
+    /** Validate a complete replacement before writing; plugin checkouts remain untouched. */
+    saveServerConfig(kind: 'mcp' | 'lsp', id: string, config: unknown): Promise<void>;
+    /** One suite's persisted MCP overrides, addressed by qualified suite id. */
+    overrides(sourceId: string, suiteId: string): Promise<McpSuiteOverrides>;
+    /**
+     * Set or clear one server's MCP override and remount it. `override === null`
+     * clears the override (back to the source config). The serverKey must exist
+     * in the suite's parsed mcp.json.
+     */
+    setOverride(sourceId: string, suiteId: string, serverKey: string, override: McpServerOverride | null): Promise<void>;
+    /**
+     * Enable or disable one declared server, addressed by the source-qualified
+     * suite id the status rows carry. The qualified id is split here rather than
+     * by callers so the separator stays a server-side detail.
+     */
+    setServerEnabled(suiteKey: string, serverKey: string, enabled: boolean): Promise<void>;
+    /**
+     * Re-run the MCP reconcile pass: retries failed mounts and clears residual
+     * tools, without changing any catalog state.
+     *
+     * Every live mount is rebuilt rather than fingerprinted: a bridge whose
+     * server died underneath it keeps matching its own resolved config, so a
+     * retry is the only path that re-verifies a mount that looks connected. The
+     * wait is bounded — the pass keeps running, so a slow server reports its
+     * outcome to the status surface instead of holding the request open.
+     */
+    retryMounts(): Promise<void>;
+    /** The persisted backend choice without the host-client probe (mount-time provider). */
+    backend(): Promise<McpBackend>;
+    /**
+     * The active MCP mount backend plus a live probe of the host client, and
+     * the download-region setting with its locale-resolved effective route —
+     * everything the plugin-config card renders.
+     */
+    backendInfo(): Promise<McpBackendInfo>;
+    /**
+     * Switch the MCP mount backend and remount every suite server through it.
+     * A host-client switch takes effect only where the host package resolves;
+     * unresolvable or unsupported transports surface as per-server diagnostics.
+     */
+    setBackend(backend: McpBackend): Promise<void>;
+    /**
+     * Drop one MCP server's OAuth grant record so the next mount re-runs the
+     * browser authorization — the path for "I picked too narrow a scope".
+     * @param serverName - the derived serverName whose folded form keys the record.
+     * @throws when the credentials service is not mounted.
+     */
+    reauthorize(serverName: string): Promise<void>;
+    /** Whether the re-authorize action can run in this composition. */
+    reauthorizeAvailable(): boolean;
+    /** MCP overrides for a supplied runtime selection, or the full market catalog when omitted. */
+    allOverrides(suites?: readonly Suite[]): Promise<Map<string, McpSuiteOverrides>>;
+    /** Resolve one editable server: its key, owning suite, root, and effective config. */
+    private resolveServerConfig;
+}

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

@@ -10,4 +10,12 @@ export interface PanelResourceStore {
     update(id: string, text: string): Promise<void>;
     remove(id: string): Promise<void>;
 }
+/**
+ * Id of one panel entry backed by a file inside an installed suite's checkout.
+ * The leading `[` is what distinguishes a plugin entry from a user-authored
+ * one; `update`/`remove` use {@link isPluginResourceId} to tell them apart.
+ */
+export declare function pluginResourceId(sourceId: string, suiteId: string, kind: UserPanelKind, name: string): string;
+/** Whether a panel entry id addresses a file inside an installed suite. */
+export declare function isPluginResourceId(id: string): boolean;
 export declare function createPanelResources(catalog: Catalog, users: Record<UserPanelKind, UserPanelStore>): Record<UserPanelKind, PanelResourceStore>;

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

@@ -0,0 +1,72 @@
+/**
+ * The host seams a catalog consumes, in one declared place.
+ *
+ * Every seam is read at call time rather than captured at construction: the
+ * credentials, tools and settings services resolve *after* `apply()` returns,
+ * so a value snapshotted when the catalog is built would stay undefined for
+ * the rest of the process. A composition root wires the seams it has;
+ * {@link resolveCatalogPorts} fills in the rest from
+ * {@link defaultCatalogPorts}, which keeps a bare `new Catalog({...})` — the
+ * shape the tests build — fully functional.
+ */
+import type { LspServerSpec, SourceKind } from '../model/types.js';
+export type { McpBackendInfo } from '../contracts/market.js';
+import type { DownloadRegionSetting } from '../contracts/settings.js';
+import type { McpBackend } from '../runtime/mcp-backend.js';
+import type { LspMountStatusSource } from '../runtime/lsp-status.js';
+import type { McpToolSnapshot } from '../runtime/mcp-status.js';
+/** A new source: its location, optional branch, and acquisition kind. */
+export interface SourceInput {
+    url: string;
+    branch?: string;
+    local?: boolean;
+    kind?: SourceKind;
+    sha256?: string;
+}
+/** A partial source update; omitted fields keep their persisted value. */
+export interface SourcePatch {
+    url?: string;
+    branch?: string;
+    local?: boolean;
+    kind?: SourceKind;
+    sha256?: string;
+}
+/** The user's direct LSP server table, keyed by server name. */
+export type LspServerTable = Record<string, LspServerSpec>;
+/** Credential-store seam backing the MCP re-authorize action. */
+export interface CredentialGrantStore {
+    deleteGrantRecord(serverName: string): Promise<void>;
+}
+/** The complete set of host seams a catalog needs; every member is resolved. */
+export interface CatalogPorts {
+    /** Live host MCP tool registry snapshot for the status surface. */
+    mcpToolSnapshot(): readonly McpToolSnapshot[];
+    /** Absent when the credentials service is not mounted in this composition. */
+    credentialsStore: CredentialGrantStore | undefined;
+    /** Flags one mount key for an explicit rebuild on the next reconcile. */
+    mcpRemount(suiteId: string, serverKey: string): void;
+    /** Flags every live mount for an explicit rebuild on the next reconcile. */
+    mcpRemountAll(): void;
+    /** Resolves the mount key owning one derived serverName; undefined when not mounted. */
+    mcpServerOwner(serverName: string): {
+        suiteId: string;
+        serverKey: string;
+    } | undefined;
+    /** Latest LSP mount diagnostics. */
+    lspStatusSource: LspMountStatusSource;
+    /** The persisted MCP mount backend choice. */
+    mcpBackend(): Promise<McpBackend>;
+    /** Persists an MCP mount backend choice. */
+    setMcpBackend(backend: McpBackend): Promise<void>;
+    /** The persisted download-region setting. */
+    downloadRegion(): Promise<DownloadRegionSetting>;
+}
+/** The seams a composition root may wire; the rest fall back to the defaults. */
+export type CatalogPortsOverride = Partial<CatalogPorts>;
+/**
+ * The seams a catalog runs on when nothing is wired. The MCP backend writer
+ * rejects rather than silently accepting a choice nothing can persist.
+ */
+export declare const defaultCatalogPorts: CatalogPorts;
+/** Fill in every seam the composition root left unwired. */
+export declare function resolveCatalogPorts(overrides?: CatalogPortsOverride): CatalogPorts;

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

@@ -1,11 +1,12 @@
 /** Narrow application interfaces consumed by the HTTP transport adapter. */
 import type { McpStatusPayload } from '../contracts/mcp-status.js';
-import type { LspStatusPayload } from '../contracts/lsp-status.js';
+import type { LspLegacySeamMigration, LspStatusPayload } from '../contracts/lsp-status.js';
 import type { OverviewPayload, SkillContent, SourceProgress, SuiteDetail } from '../contracts/market.js';
 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 { McpBackend } from '../runtime/mcp-backend.js';
 import type { ServerConfigPayload } from '../contracts/market.js';
+import type { LspServerTable, McpBackendInfo, SourceInput, SourcePatch } from './ports.js';
 /** Read-only market operations required by HTTP routes. */
 export interface MarketQueries {
     serverConfig(kind: 'mcp' | 'lsp', id: string): Promise<ServerConfigPayload>;
@@ -13,7 +14,7 @@ export interface MarketQueries {
     overview(): Promise<OverviewPayload>;
     mcpStatus(): Promise<McpStatusPayload>;
     lspStatus(): Promise<LspStatusPayload>;
-    lspServers(): Promise<Record<string, import('../model/types.js').LspServerSpec>>;
+    lspServers(): Promise<LspServerTable>;
     sourceProgress(): SourceProgress;
     suiteDetail(sourceId: string, suiteId: string): Promise<SuiteDetail>;
     skillContent(sourceId: string, suiteId: string, skillName: string): Promise<SkillContent>;
@@ -24,20 +25,8 @@ 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;
-        local?: boolean;
-        kind?: 'git' | 'local' | 'archive';
-        sha256?: string;
-    }): Promise<SourceRef>;
-    updateSource(sourceId: string, patch: {
-        url?: string;
-        branch?: string;
-        local?: boolean;
-        kind?: 'git' | 'local' | 'archive';
-        sha256?: string;
-    }): Promise<void>;
+    addSource(input: SourceInput): Promise<SourceRef>;
+    updateSource(sourceId: string, patch: SourcePatch): Promise<void>;
     /**
      * Remove a source registration; `deleteCheckout` also physically deletes
      * its managed `.sources/<id>` checkout. External local paths are never deleted.
@@ -51,22 +40,22 @@ export interface MarketMutations {
     setEnabled(sourceId: string, suiteId: string, enabled: boolean): Promise<void>;
     setSurface(sourceId: string, suiteId: string, surface: SuiteSurfaceKey, enabled: boolean): Promise<void>;
     setMcpOverride(sourceId: string, suiteId: string, serverKey: string, override: McpServerOverride | null): Promise<void>;
+    /** Enable or disable one declared MCP server by its source-qualified suite id. */
+    setMcpServerEnabled(suiteKey: string, serverKey: string, enabled: boolean): Promise<void>;
     /** Validate and persist the user's direct LSP server table. */
-    setLspServers(raw: unknown): Promise<Record<string, import('../model/types.js').LspServerSpec>>;
+    setLspServers(raw: unknown): Promise<LspServerTable>;
     setLspServerEnabled(id: string, enabled: boolean): Promise<void>;
+    /**
+     * Remove the hand-written profile layer an earlier release told the user to
+     * add for LSP; it now registers a seam this plugin owns.
+     */
+    migrateLegacyLspSeam(profile: string): Promise<LspLegacySeamMigration>;
     /** Re-run the MCP reconcile pass: retries failed mounts and clears residual tools. */
     retryMounts(): Promise<void>;
     reauthorizeMcpServer(serverName: string): Promise<void>;
     mcpReauthorizeAvailable(): boolean;
     /** The active MCP backend, host-client probe, and download region. */
-    mcpBackendInfo(): Promise<{
-        backend: McpBackend;
-        hostClient: HostMcpClientProbe;
-        downloadRegion: {
-            setting: 'auto' | 'global' | 'china';
-            effective: 'global' | 'china';
-        };
-    }>;
+    mcpBackendInfo(): Promise<McpBackendInfo>;
     /** Switch the MCP mount backend and remount every suite server through it. */
     setMcpBackend(backend: McpBackend): Promise<void>;
     /**

package/lib/types/application/snapshot-cache.d.ts

@@ -0,0 +1,51 @@
+import type { DiscoveredSuite, SourceRef, Suite, SuiteDimension, SuiteState } from '../model/types.js';
+export declare const SCAN_CACHE_TTL_MS = 30000;
+/** A coherent discovered-and-installed view for one catalog dimension. */
+export interface CatalogSnapshot {
+    revision: number;
+    sources: SourceRef[];
+    suites: Suite[];
+    enabledSuites: Suite[];
+    /** Per-source scan diagnostics (sourceId → notes), absent when clean. */
+    scanNotes?: Record<string, string[]>;
+}
+/** The state and generation counters a snapshot is built and validated against. */
+export interface SnapshotHost {
+    /** The persisted state the next snapshot is built from. */
+    readonly state: SuiteState;
+    readonly userRoot: string;
+    readonly scanProjectLayouts: boolean;
+    /** Bumped by every mutation; a snapshot built at an older revision is not cached. */
+    readonly revision: number;
+    /** Bumped by every content-changing mutation; an older scan never repopulates the cache. */
+    readonly scanGeneration: number;
+    /** Apply the install state to freshly discovered suites. */
+    project(discovered: readonly DiscoveredSuite[], state: SuiteState, dimension: SuiteDimension): Suite[];
+}
+export declare class SnapshotCache {
+    private readonly host;
+    private readonly ttls;
+    private readonly scanCache;
+    private readonly scanPromises;
+    private userSnapshot;
+    private userSnapshotExpiresAt;
+    private userSnapshotPromise;
+    /** Project-dimension snapshots keyed by project root, with TTL freshness. */
+    private readonly projectSnapshots;
+    private readonly projectSnapshotPromises;
+    constructor(host: SnapshotHost, ttls: {
+        user: number;
+        project: number;
+    });
+    /** Read one coherent user-dimension snapshot, reusing in-flight discovery. */
+    readUserCatalog(): Promise<CatalogSnapshot>;
+    /** Read one coherent project-dimension snapshot for a workspace cwd. */
+    readProjectCatalog(cwd: string): Promise<CatalogSnapshot>;
+    /** One snapshot for a dimension root, reusing cached discovery when it is fresh. */
+    build(state: SuiteState, dimension: SuiteDimension, dimensionRoot: string, skipScanCache?: boolean): Promise<CatalogSnapshot>;
+    /** Drop every cached dimension snapshot and its in-flight dedupe slot. */
+    invalidateSnapshots(): void;
+    /** Drop cached discovery and its in-flight dedupe slots. */
+    invalidateScans(): void;
+    private buildProjectSnapshot;
+}

package/lib/types/application/source-store.d.ts

@@ -0,0 +1,100 @@
+import type { SourceOverview, SourceProgress, UnmanagedSource } from '../contracts/market.js';
+import { type SourceRef } from '../model/types.js';
+import type { CatalogContext } from './catalog-context.js';
+import type { CatalogPorts, SourceInput, SourcePatch } from './ports.js';
+import type { CatalogSnapshot } from './snapshot-cache.js';
+/** Checkout status of one source, as the market overview reports it. */
+export interface SourceCheckoutStatus {
+    cloned: boolean;
+    lockCommit?: string;
+    error?: string;
+}
+export declare class SourceStore {
+    private readonly context;
+    private readonly ports;
+    private readonly headCache;
+    /** Progress snapshot of the source mutation currently in flight. */
+    private currentSourceState;
+    constructor(context: CatalogContext, ports: CatalogPorts);
+    /**
+     * Add a source and acquire it immediately (clone, download, or in-place).
+     *
+     * Git sources with an already-present checkout whose `origin` matches the
+     * input URL are adopted in place — the manual-clone repair path — so no
+     * second clone is made and no `-2` suffixed id is invented. Adopted
+     * checkouts are never deleted on source removal.
+     */
+    add(input: SourceInput): Promise<SourceRef>;
+    /** Register one unmanaged `.sources/` checkout as a source without touching its files. */
+    adopt(id: string): Promise<SourceRef>;
+    /** Unmanaged `.sources/` checkouts: present on disk, absent from state. */
+    unmanaged(): Promise<UnmanagedSource[]>;
+    /** Update one source's URL, branch, kind, or archive digest. */
+    update(sourceId: string, patch: SourcePatch): 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.
+     */
+    remove(sourceId: string, deleteCheckout?: boolean): Promise<void>;
+    /** Refresh one source checkout, or every source when sourceId is omitted. */
+    refresh(sourceId?: string): Promise<void>;
+    /** Progress snapshot for the progress route. */
+    progress(): SourceProgress;
+    /**
+     * Checkout status of one source for the market overview. A mutation owning
+     * the source right now short-circuits the probe: a Git read raced against
+     * that mutation's checkout would report a half-swapped directory.
+     */
+    describeCheckout(source: SourceRef): Promise<SourceCheckoutStatus>;
+    /** Per-source rows of the market overview for one user-dimension snapshot. */
+    overviewRows(snapshot: CatalogSnapshot): Promise<SourceOverview[]>;
+    /**
+     * Acquire one source's content by kind: clone (git), download+extract
+     * (archive), or an in-place existence check (local). Returns a lock value
+     * when the acquisition yields one (archive SHA-256, tarball fallback
+     * digest); git HEAD is read separately by the callers.
+     */
+    acquire(source: SourceRef): Promise<string | undefined>;
+    /** The filesystem location of one source. */
+    checkoutPath(source: SourceRef): string;
+    /** The last HEAD this store observed for one source, when it cached one. */
+    knownHead(sourceId: string): string | undefined;
+    /**
+     * First candidate id whose `.sources/` checkout already exists and whose
+     * `origin` remote matches the input URL (canonical-form equality) — the
+     * signature of a manual clone of the very same repository. Registered ids
+     * and checkouts of differently-origined directories never adopt.
+     */
+    private findAdoptableCheckout;
+    /**
+     * First candidate id not claimed by a registered source; for git candidates
+     * the checkout directory must also be free, so a stale or foreign directory
+     * under `.sources/` is never cloned over (it would fail `git clone` with a
+     * confusing "destination exists" error). `ownedCheckout` marks the directory
+     * the in-flight mutation already controls, keeping a rename onto it legal.
+     * Local sources skip the disk check: they read their own path in place and
+     * never occupy `.sources/`.
+     */
+    private pickSourceId;
+    /** Begin reporting progress for a source mutation. */
+    beginSourceState(sourceId: string, step: string, cloned: boolean): void;
+    /** Advance the in-flight source mutation step. */
+    updateSourceStep(step: string): void;
+    /** Stop reporting source mutation progress. */
+    endSourceState(): void;
+}
+/** Read a checkout's HEAD when it is a Git repository. */
+export declare function tryHead(dir: string): Promise<string | undefined>;
+/**
+ * The codeload tarball URL of a GitHub repository, or undefined for any
+ * other host. `https://github.com/<owner>/<repo>` maps to
+ * `https://codeload.github.com/<owner>/<repo>/tar.gz/refs/heads/<branch>`
+ * (or `/tar.gz/HEAD` for the default branch) — the git-protocol fallback
+ * when a clone cannot get through but plain HTTPS file download can.
+ */
+export declare function codeloadTarballUrl(url: string, branch: string | undefined): string | undefined;

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

@@ -1,3 +1,4 @@
+import { archiveFormatOf, type ArchiveFormat } from '../model/types.js';
 /** Hard cap on archive download size (mirrors Claude Code's archive limit). */
 export declare const ARCHIVE_MAX_BYTES: number;
 /** Hard cap on the total decompressed bytes one archive may write. */
@@ -27,10 +28,8 @@ export interface ArchiveInstallResult {
     /** SHA-256 hex digest of the downloaded payload (usable as a lock value). */
     sha256: string;
 }
-/** Recognized archive payload kinds. */
-export type ArchiveFormat = 'zip' | 'tar' | 'targz';
-/** Classify an archive URL by extension; undefined when unsupported. */
-export declare function archiveFormatOf(url: string): ArchiveFormat | undefined;
+/** Archive vocabulary (format kinds and URL classification) shared with the model layer. */
+export { archiveFormatOf, type ArchiveFormat };
 /** Download the payload to a temp file, enforcing the size cap and digest. */
 export declare function downloadArchive(url: string, tempFile: string, options?: ArchiveOptions): Promise<string>;
 /**
@@ -39,10 +38,3 @@ export declare function downloadArchive(url: string, tempFile: string, options?:
  * then swap into `dest`. Returns the payload digest.
  */
 export declare function archiveInstall(url: string, dest: string, options?: ArchiveOptions): Promise<ArchiveInstallResult>;
-/** Walk the extracted tree and reject any symlink whose target resolves outside `root`. */
-declare function assertNoEscapingSymlinks(root: string): Promise<void>;
-/** Test seam: run the symlink-containment walk against a prepared tree. */
-export declare const assertNoEscapingSymlinksForTest: typeof assertNoEscapingSymlinks;
-/** Probe whether a path exists and is a directory. */
-export declare function isDirectory(path: string): Promise<boolean>;
-export {};

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

@@ -1,5 +1,9 @@
 import type { SuiteMarkdownResource } from '../model/types.js';
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** `Array.isArray` narrows to `any[]`; declarations are untrusted, so the elements stay `unknown`. */
+export declare function isUnknownArray(value: unknown): value is unknown[];
+/** True only for an array whose every element is a string. */
+export declare function isStringArray(value: unknown): value is string[];
 /** 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. */

package/lib/types/catalog/fs-probes.d.ts

@@ -0,0 +1,10 @@
+/** Dot-directories and dependency trees that never hold suite content. */
+export declare const DOT_DIRS: Set<string>;
+/** Whether `path` is an existing directory (symlinks followed for the final component). */
+export declare function isDirectory(path: string): Promise<boolean>;
+/** Whether `path` is an existing regular file. */
+export declare function isFile(path: string): Promise<boolean>;
+/** Whether any entry (file, directory, symlink) exists at `path`. */
+export declare function pathExists(path: string): Promise<boolean>;
+/** Absolute paths of the non-hidden child directories of `dir`, in readdir order. */
+export declare function listChildDirs(dir: string): Promise<string[]>;

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

@@ -6,6 +6,11 @@ export interface ManifestCandidate {
     kind: ManifestKind;
     path: string;
 }
+/**
+ * Every manifest file a directory carries, in selection order: highest
+ * precedence first, aliases of one dialect in their own listed order.
+ */
+export declare function detectManifests(dir: string): Promise<ManifestCandidate[]>;
 /** The highest-precedence manifest file a directory carries, if any. */
 export declare function detectManifest(dir: string): Promise<ManifestCandidate | undefined>;
 /** Whether a directory carries any known suite manifest. */
@@ -14,15 +19,20 @@ export declare function hasSuiteManifest(dir: string): Promise<boolean>;
 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.
+ * Read a suite manifest by walking the layout priority list from the top.
+ *
+ * A candidate that cannot be parsed or validated fails closed *for itself*:
+ * its diagnostics are recorded and the next candidate by priority is tried.
+ * Diagnostics of a rejected candidate that a lower-priority manifest replaced
+ * go to `fallbacks`, so the winner stays usable while the caller can still
+ * report why the higher-priority declaration was ignored. The winner's own
+ * diagnostics stay in `errors` and remain fatal.
  */
 export declare function readManifest(root: string, errors: string[], hint: ({
     name?: string;
     version?: string;
     description?: string;
-} & SuiteComponents) | undefined): Promise<SuiteManifest | undefined>;
+} & SuiteComponents) | undefined, fallbacks?: string[]): Promise<SuiteManifest | undefined>;
 export interface MarketplaceEntry extends SuiteComponents {
     layout?: ManifestKind;
     strict?: boolean;
@@ -31,12 +41,14 @@ export interface MarketplaceEntry extends SuiteComponents {
     description?: string;
     /** Claude Code: inline `lspServers` table declared on the entry itself. */
     lspServers?: unknown;
-    /** Claude Code: a relative path string or `{ source: 'url', url }`.
+    /** Claude Code: a relative path string, `{ source: 'url', url }`, or the
+     *  `{ source: 'github', repo: 'owner/name' }` shorthand.
      *  Codex: `{ source: 'local', path }` or `{ source: 'remote', url }`. */
     source: string | {
         source?: string;
         url?: string;
         path?: string;
+        repo?: string;
     };
 }
 export interface Marketplace {
@@ -55,11 +67,6 @@ export interface ReadMarketplaceResult extends Marketplace {
  * or invalid catalog allows the next candidate to be tried.
  */
 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
- *  `undefined` for remote-URL entries that are not present in the clone. */
-export declare function marketplaceEntryDir(checkoutDir: string, entry: MarketplaceEntry): string | undefined;
 /**
  * Resolve a repo-level name for source-id derivation, in precedence order:
  * marketplace plugin entry name > marketplace name > root manifest name >
@@ -67,9 +74,3 @@ export declare function marketplaceEntryDir(checkoutDir: string, entry: Marketpl
  * basename is only the fallback.
  */
 export declare function repoName(checkoutDir: string): Promise<string>;
-/** The winning manifest's declared `skills` path (string or array), or undefined. */
-export declare function declaredSkillsPath(root: string): Promise<unknown>;
-/** The winning manifest's inline `mcpServers`, or undefined. */
-export declare function declaredMcpServers(root: string): Promise<Record<string, unknown> | undefined>;
-/** The winning manifest's inline `lspServers`, or undefined. */
-export declare function declaredLspServers(root: string): Promise<Record<string, unknown> | undefined>;

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

@@ -1,4 +1,4 @@
-import type { Suite, SuiteDimension } from '../model/types.js';
+import type { DiscoveredSuite, SuiteDimension } from '../model/types.js';
 import { type ProjectLayout } from '../model/layouts.js';
 /**
  * Project-local directory conventions, in precedence order. Each entry maps
@@ -11,4 +11,4 @@ export type NativeProjectDir = ProjectLayout;
  * convention directory that carries content becomes one synthetic suite;
  * empty or absent directories contribute nothing.
  */
-export declare function discoverNativeProjectSuites(projectRoot: string, dimension: SuiteDimension): Promise<Suite[]>;
+export declare function discoverNativeProjectSuites(projectRoot: string, dimension: SuiteDimension): Promise<DiscoveredSuite[]>;

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

@@ -1,14 +1,29 @@
+import { expandHomePath } from '@deepseek-ai/dsh-home-paths';
 /** Source checkouts live under `<dimensionRoot>/.sources/<sourceId>/`. */
 export declare const SOURCES_DIR_NAME = ".sources";
-/** Per-suite mutable data directory (the `${PLUGIN_DATA}` placeholder). */
-export declare const DATA_DIR_NAME = "data";
 export declare const STATE_FILE_NAME = "state.json";
-/** Expand a leading `~/` (or `~\` on Windows) to the home directory; other values pass through. */
-export declare function expandHome(path: string): string;
-/** Resolve the harness home (`$DSH_HOME` or `~/.dsh`). */
+/**
+ * Expand a leading `~`, `~/`, or `~\` to the OS home; other values pass
+ * through. The harness helper owns the platform rules, so a configured path is
+ * read back the same way on every host.
+ */
+export declare const expandHome: typeof expandHomePath;
+/**
+ * Resolve the harness home (`$DSH_HOME` or `~/.dsh`) through the harness
+ * helper: precedence and tilde expansion stay the harness's, and a blank
+ * `$DSH_HOME` reads as unset rather than resolving the home to the current
+ * working directory.
+ */
 export declare function resolveDshHome(): string;
 /** Resolve the canonical user-dimension root. Legacy overrides are migration inputs only. */
 export declare function resolveUserRoot(_configUserRoot?: string): string;
+/**
+ * Resolve the shared user-level Agent layout root (`$DSH_AGENTS_HOME` or
+ * `~/.agents`): where this plugin stores the resources and service
+ * declarations the user authors by hand. A blank override reads as unset, the
+ * same rule the harness applies to its own home.
+ */
+export declare function resolveAgentsRoot(): string;
 /**
  * Resolve the suite data root hosting `${PLUGIN_DATA}` directories and the
  * MCP overrides. Defaults under the user root so the whole plugin persists
@@ -19,12 +34,10 @@ export declare function resolveDataRoot(_configDataRoot?: string, _configUserRoo
 export declare function findProjectRoot(cwd: string): Promise<string>;
 /** Resolve the project-dimension suite root for a workspace cwd. */
 export declare function resolveProjectRoot(cwd: string): Promise<string>;
-/** Source checkout directory for one source id. */
+/** Directory holding every source checkout of one dimension root. */
 export declare function sourcesDir(dimensionRoot: string): string;
-/** Source checkout directory for one source id. */
+/** Checkout directory of one source inside a dimension root. */
 export declare function sourceCheckoutDir(dimensionRoot: string, sourceId: string): string;
-/** Per-suite data directory for `${PLUGIN_DATA}`. */
-export declare function suiteDataDir(dataRoot: string, suiteId: string): string;
 /**
  * Suite-qualified key: `${sourceId}/${suiteId}`. Suite ids are unique within a
  * source only (two sources may both ship a suite named "utils"), so every
@@ -32,14 +45,39 @@ export declare function suiteDataDir(dataRoot: string, suiteId: string): string;
  * bare suite id silently collides across sources.
  */
 export declare function qualifiedSuiteId(sourceId: string, suiteId: string): string;
-/** Async existence probe that follows symlinks for a final component. */
-export declare function isDirectory(path: string): Promise<boolean>;
-/** Async existence probe for any entry (file, directory, symlink). */
-export declare function pathExists(path: string): Promise<boolean>;
+/**
+ * The data directory `${PLUGIN_DATA}` resolves to for one suite: a
+ * source-qualified directory under the plugin storage root, shared by every
+ * surface of that suite so MCP servers, skills and commands see one location.
+ */
+export declare function suiteDataDir(dataRoot: string, sourceId: string, suiteId: string): string;
+/** The slice of a `node:path` implementation a containment test needs. */
+export interface PathFlavor {
+    relative(from: string, to: string): string;
+    isAbsolute(path: string): boolean;
+    sep: string;
+}
+/**
+ * Whether `candidate` is `root` itself or a path below it, compared on whole
+ * path segments by `flavor`'s rules so a sibling whose name merely starts with
+ * the root's (`/a/bc` against `/a/b`) does not count as contained.
+ *
+ * `relative` resolves both operands with those rules before comparing, so the
+ * answer never depends on how each side was spelled: a checkout read from
+ * configuration as `C:/x/y` and an entry resolved to `C:\x\y\plugins\a` stay
+ * contained, Windows compares drive letters and segments case-insensitively,
+ * and an unnormalized `..` inside the candidate is resolved rather than
+ * trusted as text. On POSIX a backslash stays the ordinary filename character
+ * it is — folding separators there would invent containment that does not
+ * exist.
+ *
+ * `flavor` is injectable so the win32 rules stay covered by a POSIX test run.
+ */
+export declare function isWithinUnder(flavor: PathFlavor, root: string, candidate: string): boolean;
+/** Whether `candidate` is `root` itself or a path below it, by the host's path rules. */
+export declare function isWithin(root: string, candidate: string): boolean;
 /** Sanitize a plugin or server id into `[a-z0-9-]` (lowercased). */
 export declare function sanitizeId(raw: string): string;
-/** Derive a source id from a repository URL or local path: last path segment, `.git` stripped. */
-export declare function deriveSourceId(url: string): string;
 /**
  * Derive candidate source ids from a git URL or local path, most preferred
  * first: the sanitized basename, then an owner-prefixed variant (`owner-repo`)

package/lib/types/catalog/plugin-variables.d.ts

@@ -0,0 +1,16 @@
+import type { Suite } from '../model/types.js';
+/** The absolute paths one expansion can supply; an absent entry leaves its variable verbatim. */
+export interface PluginPathContext {
+    /** Suite checkout root: `${PLUGIN_ROOT}` and its dialect aliases. */
+    root?: string;
+    /** Per-suite data directory: `${PLUGIN_DATA}` and its aliases. */
+    data?: string;
+    /** Directory holding the skill file: `${CLAUDE_SKILL_DIR}`. */
+    skillDir?: string;
+    /** Calling session's project directory: `${CLAUDE_PROJECT_DIR}` and its aliases. */
+    projectDir?: string;
+}
+/** The suite root `${PLUGIN_ROOT}` and its dialect aliases resolve to. */
+export declare function pluginRootOf(suite: Pick<Suite, 'manifest' | 'root'>): string | undefined;
+/** Replace every path variable the context can resolve; other text stays exactly as written. */
+export declare function expandPluginPaths(text: string, context: PluginPathContext): string;