@khorsheed/dsh-capability-catalog 0.1.98 → 0.1.99

package/lib/types/tool-face.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Reading the tools side of the capability face: the visible schemas in a
+ * scope, the author-declared origin tags behind them, and the MCP server
+ * names the `mcp__` prefixes imply.
+ *
+ * Extracted from the service so the Remote verbs and the pure-data evidence
+ * producer (`evidence.ts`) read the tools registry through ONE
+ * implementation — the digest parity between them is by construction, not by
+ * two copies agreeing today. Nothing here catches a `schemas()` failure:
+ * whether a failed read rejects the call (the Remote verbs' choice) or is
+ * recorded as an unavailable section (the evidence producer's choice) is the
+ * caller's policy.
+ * @module @khorsheed/dsh-capability-catalog/tool-face
+ */
+import { type ToolOrigin } from './tool-origin.ts';
+import type { CatalogJsonValue } from './types.ts';
+/** The slice of the tools registry the catalog reads (optional). */
+export interface CatalogToolsSlice {
+    schemas: (scope?: unknown) => readonly ToolSchemaLike[];
+    get?: (name: string, scope?: unknown) => object | undefined;
+}
+/** Minimal ToolSchema shape (model-facing name/description/parameters). */
+export interface ToolSchemaLike {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters?: CatalogJsonValue;
+}
+/** The tools side of one reading position, collected once. */
+export interface ToolFaceCollection {
+    /** The visible tool schemas in the scope (the set the model sees). */
+    readonly schemas: readonly ToolSchemaLike[];
+    /** tool name → author-declared origin, where the tag could be read and validated. */
+    readonly origins: ReadonlyMap<string, ToolOrigin>;
+    /** MCP server names derived from the `mcp__`-prefixed visible tools. */
+    readonly mcpServerNames: readonly string[];
+    /**
+     * Visible tools whose origin tag could not be read (`get` absent from the
+     * slice, returned undefined, or carried an invalid tag) and which therefore
+     * fall back to heuristic channel attribution. Tool NAMES only — never error
+     * text, which may carry paths.
+     */
+    readonly untaggedOrigins: readonly string[];
+}
+/**
+ * The visible tool schemas in a scope, or the global layer when no scope is
+ * given; an empty list when the registry is absent.
+ */
+export declare function toolSchemasFacing(tools: CatalogToolsSlice | undefined, scope: unknown): readonly ToolSchemaLike[];
+/**
+ * The origin tags behind the given schemas, read via `tools.get(name)` so the
+ * `Symbol.for('dsh.tool.origin')` tag on the retained definition survives
+ * (the system-prompt assembly strips it, but `get()` returns the full
+ * definition). A schema the registry cannot hand back contributes no tag —
+ * the tool falls back to heuristics and is named in `untaggedOrigins`.
+ */
+export declare function toolOriginsFacing(tools: CatalogToolsSlice | undefined, schemas: readonly ToolSchemaLike[], scope: unknown, warn: (message: string) => void): {
+    readonly origins: ReadonlyMap<string, ToolOrigin>;
+    readonly untaggedOrigins: readonly string[];
+};
+/** MCP server names from live `mcp__`-prefixed tools (prefix-derived baseline). */
+export declare function mcpServerNamesFacing(schemas: readonly ToolSchemaLike[]): readonly string[];
+/**
+ * Collect the whole tools side of one reading position with ONE `schemas()`
+ * call, so the rows, the origin tags and the MCP names cannot disagree about
+ * which registry state they read.
+ */
+export declare function collectToolFace(tools: CatalogToolsSlice | undefined, scope: unknown, warn: (message: string) => void): ToolFaceCollection;
+//# sourceMappingURL=tool-face.d.ts.map

package/lib/types/tool-face.js

@@ -0,0 +1,82 @@
+/**
+ * Reading the tools side of the capability face: the visible schemas in a
+ * scope, the author-declared origin tags behind them, and the MCP server
+ * names the `mcp__` prefixes imply.
+ *
+ * Extracted from the service so the Remote verbs and the pure-data evidence
+ * producer (`evidence.ts`) read the tools registry through ONE
+ * implementation — the digest parity between them is by construction, not by
+ * two copies agreeing today. Nothing here catches a `schemas()` failure:
+ * whether a failed read rejects the call (the Remote verbs' choice) or is
+ * recorded as an unavailable section (the evidence producer's choice) is the
+ * caller's policy.
+ * @module @khorsheed/dsh-capability-catalog/tool-face
+ */
+import { MCP_TOOL_PREFIX } from './channels.js';
+import { toolOrigin, isValidOrigin } from './tool-origin.js';
+/**
+ * The visible tool schemas in a scope, or the global layer when no scope is
+ * given; an empty list when the registry is absent.
+ */
+export function toolSchemasFacing(tools, scope) {
+    if (tools?.schemas === undefined)
+        return [];
+    return scope === undefined ? tools.schemas() : tools.schemas(scope);
+}
+/**
+ * The origin tags behind the given schemas, read via `tools.get(name)` so the
+ * `Symbol.for('dsh.tool.origin')` tag on the retained definition survives
+ * (the system-prompt assembly strips it, but `get()` returns the full
+ * definition). A schema the registry cannot hand back contributes no tag —
+ * the tool falls back to heuristics and is named in `untaggedOrigins`.
+ */
+export function toolOriginsFacing(tools, schemas, scope, warn) {
+    const out = new Map();
+    const untagged = [];
+    if (tools?.get === undefined)
+        return { origins: out, untaggedOrigins: untagged };
+    for (const schema of schemas) {
+        const def = scope === undefined ? tools.get(schema.name) : tools.get(schema.name, scope);
+        if (def === undefined) {
+            // `schemas()` and `get()` disagree for this scope — the author's origin
+            // tag (if any) cannot be read, so the tool falls back to heuristics.
+            warn(`capability-catalog: tool "${schema.name}" is visible but ctx.tools.get() is undefined in this scope — its origin tag cannot be read; it will be classified by heuristics`);
+            untagged.push(schema.name);
+            continue;
+        }
+        const origin = toolOrigin(def);
+        if (origin !== undefined) {
+            if (!isValidOrigin(origin)) {
+                warn(`capability-catalog: tool "${schema.name}" origin channel "${String(origin.channel)}" is not a known channel (plugin/builtin/mcp) — ignoring the tag, falling back to heuristics`);
+                untagged.push(schema.name);
+                continue;
+            }
+            out.set(schema.name, origin);
+        }
+    }
+    return { origins: out, untaggedOrigins: untagged };
+}
+/** MCP server names from live `mcp__`-prefixed tools (prefix-derived baseline). */
+export function mcpServerNamesFacing(schemas) {
+    const names = [];
+    for (const schema of schemas) {
+        if (!schema.name.startsWith(MCP_TOOL_PREFIX))
+            continue;
+        const rest = schema.name.slice(MCP_TOOL_PREFIX.length);
+        const sep = rest.indexOf('__');
+        const server = sep > 0 ? rest.slice(0, sep) : rest;
+        if (server.length > 0 && !names.includes(server))
+            names.push(server);
+    }
+    return names;
+}
+/**
+ * Collect the whole tools side of one reading position with ONE `schemas()`
+ * call, so the rows, the origin tags and the MCP names cannot disagree about
+ * which registry state they read.
+ */
+export function collectToolFace(tools, scope, warn) {
+    const schemas = toolSchemasFacing(tools, scope);
+    const { origins, untaggedOrigins } = toolOriginsFacing(tools, schemas, scope, warn);
+    return { schemas, origins, mcpServerNames: mcpServerNamesFacing(schemas), untaggedOrigins };
+}

package/lib/types/types.d.ts

@@ -120,6 +120,36 @@ export interface CatalogChannelSummary {
     readonly channel: string;
     readonly count: number;
 }
+/**
+ * Evidence-grade completeness of ONE snapshot section's measurement.
+ *
+ * The three states are a contract about what the rows may be read as:
+ *
+ * - `complete` — the section was measured and everything found is included.
+ *   Zero rows is complete-with-zero (scanned, nothing there), which is
+ *   distinguishable from a failure.
+ * - `partial` — some sources failed, so the rows are a SUBSET. `reason`
+ *   names the failed source class (never secret content, never raw error
+ *   text, which may carry paths).
+ * - `unavailable` — the section could not be measured at all (the service
+ *   is not installed, or the read failed, or permission was denied). The
+ *   rows carry no meaning.
+ *
+ * A consumer MUST treat `partial` and `unavailable` as "not verified" —
+ * never as complete, and never as "the section is empty".
+ */
+export interface CatalogSectionCompleteness {
+    readonly state: 'complete' | 'partial' | 'unavailable';
+    /** Why the section is not complete; absent when it is. */
+    readonly reason?: string;
+}
+/** Per-section completeness of a snapshot, keyed by the section names the snapshot carries. */
+export interface CatalogSnapshotCompleteness {
+    readonly skills?: CatalogSectionCompleteness;
+    readonly tools?: CatalogSectionCompleteness;
+    readonly mcpServers?: CatalogSectionCompleteness;
+    readonly channels?: CatalogSectionCompleteness;
+}
 /** Full catalog snapshot. */
 export interface CapabilityCatalogSnapshot {
     readonly skills: readonly CatalogSkillRow[];
@@ -134,6 +164,13 @@ export interface CapabilityCatalogSnapshot {
     readonly sha?: string;
     /** The agent preset this snapshot was taken under; absent when none resolved. */
     readonly preset?: string;
+    /**
+     * Evidence-grade per-section completeness, attached only by evidence
+     * production (the Remote listing/fingerprint verbs never set it, so their
+     * wire form is unchanged). Like `sha`, it is NOT part of the canonical
+     * form `hashOf` digests.
+     */
+    readonly completeness?: CatalogSnapshotCompleteness;
 }
 /** Fresh detail of one skill (body + metadata), loaded on demand. */
 export interface CatalogSkillDetail {
@@ -152,7 +189,9 @@ export interface CatalogSkillDetail {
     /** Declared credentials + their configured state (metadata.credentials only). */
     readonly credentials?: readonly CatalogCredentialState[];
     /** Env-var references detected in the skill body (read-only, informational —
-     * typically provided by the runtime/caller, NOT user-configurable here). */
+     * typically provided by the runtime/caller, NOT user-configurable here). A key
+     * already declared in metadata.credentials is excluded — it renders in the
+     * credential form instead. */
     readonly environmentRefs?: readonly string[];
     /** Bundle-relative file paths (SKILL.md + scripts/assets/references) for a directory side. */
     readonly files?: readonly string[];
@@ -294,22 +333,4 @@ export interface CatalogCredentialSetRequest {
     readonly key: string;
     readonly value: string;
 }
-/** Remote surface the browser card binds through. */
-export interface CapabilityCatalogRemote {
-    readonly snapshot: (workdir?: string) => Promise<CapabilityCatalogSnapshot>;
-    /** The capability face of one preset, with its `sha` (see the host half). */
-    readonly snapshotFor: (presetId?: string, workdir?: string) => Promise<CapabilityCatalogSnapshot>;
-    /** The capability face of one mode as a LISTING (no fingerprint work). */
-    readonly snapshotAt: (presetId?: string, workdir?: string) => Promise<CapabilityCatalogSnapshot>;
-    /** Every mode's face in one call, for the cross-mode comparison view. */
-    readonly modeFaces: (workdir?: string) => Promise<readonly CatalogModeFace[]>;
-    /** Read one capability at a mode's scope, or the default mode when omitted. */
-    readonly detail: (name: string, workdir?: string, presetId?: string) => Promise<CatalogSkillDetail | undefined>;
-    readonly readSkillFile: (name: string, filePath: string, workdir?: string, presetId?: string) => Promise<CatalogSkillFileRead | undefined>;
-    readonly listDirSkills: (dirPath: string) => Promise<readonly CatalogDirSkillInfo[]>;
-    readonly setCredential: (request: CatalogCredentialSetRequest) => Promise<boolean>;
-    readonly addSkill: (request: CatalogAddSkillRequest) => Promise<CatalogAddSkillResult>;
-    readonly deleteSkill: (name: string, workdir?: string, presetId?: string) => Promise<CatalogDeleteSkillResult>;
-    readonly pickDirectory: () => Promise<string | null>;
-}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -9,7 +9,7 @@
     "catalog",
     "skills"
   ],
-  "version": "0.1.98",
+  "version": "0.1.99",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -18,10 +18,6 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
     "./client": {
       "types": "./lib/types/client/index.d.ts",
       "default": "./lib/client.js"
@@ -58,26 +54,32 @@
     "compat": {
       "minHost": "0.1.5-rc.1",
       "notes": "0.1.5-rc.1 full-line boot-verified 2026-09-25 (42 packages including capture) through the three compat layers: preset-registry dual-name probe, dual-shape typert codecs, and typert faces carrying zod@4; 0.1.7-rc.2 is the 3080 production-verified line",
-      "verifiedHost": "0.1.7-rc.2"
-    }
+      "verifiedHost": "0.2.1-rc.1"
+    },
+    "runtimeDependencies": [
+      "js-yaml"
+    ]
   },
   "license": "MIT",
+  "engines": {
+    "dsh": ">=0.1.5-rc.1 <0.3.0-0"
+  },
   "dependencies": {
+    "js-yaml": "^4.3.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
     "react": "^18.2.0"
   },
   "peerDependenciesMeta": {

package/lib/invariant.js

@@ -1,25 +0,0 @@
-//#region lib/types/invariant.js
-/**
-* Package-owned invariant companion for `@khorsheed/dsh-capability-catalog`.
-* @module @khorsheed/dsh-capability-catalog/invariant
-*/
-const PACKAGE_NAME = "@khorsheed/dsh-capability-catalog";
-/** Cordis companion plugin name. */
-const name = "capability-catalog-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/**
-* No runtime invariant: the catalog is read-only over existing registries
-* (ctx.skills / ctx.tools) and the add-skill write path validates its inputs
-* before touching disk. The unit tests exercise the channel attribution,
-* skill decoding, and the wire projection.
-*/
-const install = () => {};
-/**
-* Register this package's invariant companion.
-* @param ctx - Cordis context carrying the invariant service.
-* @returns the installed registration's disposer after setup succeeds.
-*/
-const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-//#endregion
-export { apply, inject, name };

package/lib/types/invariant.d.ts

@@ -1,16 +0,0 @@
-/**
- * Package-owned invariant companion for `@khorsheed/dsh-capability-catalog`.
- * @module @khorsheed/dsh-capability-catalog/invariant
- */
-import type { Context } from '@deepseek-ai/cordis';
-/** Cordis companion plugin name. */
-export declare const name = "capability-catalog-invariant";
-/** Service required before the companion can reserve package ownership. */
-export declare const inject: string[];
-/**
- * Register this package's invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export declare const apply: (ctx: Context) => Promise<() => void>;
-//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -1,23 +0,0 @@
-/**
- * Package-owned invariant companion for `@khorsheed/dsh-capability-catalog`.
- * @module @khorsheed/dsh-capability-catalog/invariant
- */
-const PACKAGE_NAME = '@khorsheed/dsh-capability-catalog';
-/** Cordis companion plugin name. */
-export const name = 'capability-catalog-invariant';
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants'];
-/**
- * No runtime invariant: the catalog is read-only over existing registries
- * (ctx.skills / ctx.tools) and the add-skill write path validates its inputs
- * before touching disk. The unit tests exercise the channel attribution,
- * skill decoding, and the wire projection.
- */
-const install = () => { };
-/**
- * Register this package's invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-/* jscpd:ignore-end */