@nospt/plugin-dev-ai-hub-common 0.2.4 → 0.3.1

package/dist/index.cjs.js

@@ -1,13 +1,39 @@
 'use strict';
 
-var schemas = require('./schemas.cjs.js');
-var installPaths = require('./installPaths.cjs.js');
+var resources = require('./resources.cjs.js');
+var telemetry = require('./telemetry.cjs.js');
 
 
 
-exports.AiAssetFrontmatterSchema = schemas.AiAssetFrontmatterSchema;
-exports.AiToolEnum = schemas.AiToolEnum;
-exports.AssetTypeEnum = schemas.AssetTypeEnum;
-exports.getInstallPath = installPaths.getInstallPath;
-exports.getInstallPathsForAsset = installPaths.getInstallPathsForAsset;
+exports.AGENT_LINK_CAPABLE_FRAMEWORKS = resources.AGENT_LINK_CAPABLE_FRAMEWORKS;
+exports.ANNOTATION_COMPATIBLE_FRAMEWORKS = resources.ANNOTATION_COMPATIBLE_FRAMEWORKS;
+exports.ANNOTATION_HELP = resources.ANNOTATION_HELP;
+exports.ANNOTATION_VERSION = resources.ANNOTATION_VERSION;
+exports.DEVAIHUB_ANNOTATION_PREFIX = resources.DEVAIHUB_ANNOTATION_PREFIX;
+exports.INSTALLABLE_FRAMEWORKS = resources.INSTALLABLE_FRAMEWORKS;
+exports.KNOWN_FRAMEWORKS = resources.KNOWN_FRAMEWORKS;
+exports.MARKETPLACE_CAPABLE_FRAMEWORKS = resources.MARKETPLACE_CAPABLE_FRAMEWORKS;
+exports.MCP_LINK_CAPABLE_FRAMEWORKS = resources.MCP_LINK_CAPABLE_FRAMEWORKS;
+exports.PROMPT_LINK_CAPABLE_FRAMEWORKS = resources.PROMPT_LINK_CAPABLE_FRAMEWORKS;
+exports.RESOURCE_TYPES = resources.RESOURCE_TYPES;
+exports.RESOURCE_TYPE_REGISTRY = resources.RESOURCE_TYPE_REGISTRY;
+exports.expandInstallFrameworks = resources.expandInstallFrameworks;
+exports.getAgentInstallLinks = resources.getAgentInstallLinks;
+exports.getBodyShape = resources.getBodyShape;
+exports.getFrameworks = resources.getFrameworks;
+exports.getInstallSteps = resources.getInstallSteps;
+exports.getMarketplaceAddCommands = resources.getMarketplaceAddCommands;
+exports.getMarketplaceInstallTemplate = resources.getMarketplaceInstallTemplate;
+exports.getMarketplaceRepoSlug = resources.getMarketplaceRepoSlug;
+exports.getMarketplaceTeamSnippet = resources.getMarketplaceTeamSnippet;
+exports.getMcpInstallLinks = resources.getMcpInstallLinks;
+exports.getPromptInstallLinks = resources.getPromptInstallLinks;
+exports.getResourceInstallTarget = resources.getResourceInstallTarget;
+exports.hasCopyableBody = resources.hasCopyableBody;
+exports.hasDownloadableArtifact = resources.hasDownloadableArtifact;
+exports.isResourceType = resources.isResourceType;
+exports.normalizeFramework = resources.normalizeFramework;
+exports.resolveCapableFrameworks = resources.resolveCapableFrameworks;
+exports.TelemetryActionEnum = telemetry.TelemetryActionEnum;
+exports.TelemetryEventInputSchema = telemetry.TelemetryEventInputSchema;
 //# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;"}
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -1,179 +1,322 @@
 import { z } from 'zod';
 
-type AssetType = 'instruction' | 'agent' | 'skill' | 'workflow';
-type AiTool = 'all' | 'github-copilot' | 'claude-code' | 'google-gemini' | 'cursor';
-/** Lightweight summary returned by list endpoints — no markdown content. */
-interface AiAssetSummary {
-    id: string;
-    providerId: string;
-    name: string;
-    /** Human-readable display name. Falls back to `name` when not set. */
-    label?: string;
-    description: string;
-    type: AssetType;
-    tools: AiTool[];
-    tags: string[];
-    author: string;
-    icon?: string;
-    version: string;
-    installCount: number;
-    syncedAt: string;
-    createdAt: string;
-    updatedAt: string;
+/**
+ * The v2 read contract: AiResource vocabulary, the flat ResourceSummary
+ * returned by the backend, and the shared framework resolver (ADR-0003).
+ *
+ * The legacy asset-model types in `types.ts` coexist with this module until
+ * the legacy silo is deleted (slice 8, issue #34).
+ */
+/** The six canonical `spec.type` values of an AiResource (ADR-0003, ADR-0010). */
+declare const RESOURCE_TYPES: readonly ["skill", "agent", "hook", "mcp-config", "plugin", "marketplace"];
+type ResourceType = (typeof RESOURCE_TYPES)[number];
+declare function isResourceType(value: unknown): value is ResourceType;
+/** Annotation prefix owned by DevAI Hub. */
+declare const DEVAIHUB_ANNOTATION_PREFIX = "devaihub.io";
+/** Comma-separated compatible-framework tokens (non-skill read path, ADR-0003). */
+declare const ANNOTATION_COMPATIBLE_FRAMEWORKS = "devaihub.io/compatible-frameworks";
+/** Optional semantic version string, displayed on cards. */
+declare const ANNOTATION_VERSION = "devaihub.io/version";
+/** Optional free-form help text shown on the detail panel. */
+declare const ANNOTATION_HELP = "devaihub.io/help";
+/** Known framework tokens; unknown tokens pass through as-is (ADR-0003). */
+declare const KNOWN_FRAMEWORKS: readonly ["github-copilot", "claude-code", "cursor", "google-gemini", "all"];
+type FrameworkToken = (typeof KNOWN_FRAMEWORKS)[number];
+/**
+ * Normalise a framework token: trim, lowercase, resolve aliases
+ * (`claude` → `claude-code`). Unknown tokens pass through literally.
+ */
+declare function normalizeFramework(token: string): string;
+/**
+ * The minimal structural shape of an AiResource entity that the read helpers
+ * need. A real `@backstage/catalog-model` `Entity` satisfies it, but keeping
+ * the shape local means `-common` (and therefore the frontend) never depends
+ * on catalog packages (architecture.md).
+ */
+interface AiResourceEntityLike {
+    metadata: {
+        annotations?: Record<string, string>;
+    };
+    spec?: {
+        type?: unknown;
+        /** Native skill subtype field: compatible frameworks. */
+        agents?: unknown;
+        [key: string]: unknown;
+    };
 }
-interface AiAsset {
-    id: string;
-    providerId: string;
-    name: string;
-    /** Human-readable display name. Falls back to `name` when not set. */
-    label?: string;
-    description: string;
-    type: AssetType;
-    tools: AiTool[];
-    tags: string[];
-    author: string;
-    icon?: string;
-    version: string;
-    /** Override the install path for all tools */
-    installPath?: string;
-    /** Override the install path per tool */
-    installPaths?: Record<string, string>;
-    /** Pure markdown content from the .md file, never modified */
-    content: string;
-    /** Raw YAML of the metadata file */
-    yamlRaw: string;
-    /** Extra metadata stored from the envelope (e.g. resources for skills) */
-    metadata?: Record<string, unknown>;
+/**
+ * Resolve the compatible frameworks of an AiResource (ADR-0003):
+ * 1. `skill` with a non-empty `spec.agents` → the native field;
+ * 2. otherwise → the `devaihub.io/compatible-frameworks` annotation
+ *    (also the fallback for a skill whose `spec.agents` is empty/absent);
+ * 3. otherwise → `[]`.
+ * Tokens are normalised; unknown tokens pass through.
+ */
+declare function getFrameworks(entity: AiResourceEntityLike): string[];
+/**
+ * Icon identifiers for the type→card registry. `-common` is imported by the
+ * backend, so it stays React-free: the frontend maps these identifiers to
+ * actual icon components.
+ */
+type ResourceTypeIcon = 'tools' | 'robot' | 'flash' | 'plug' | 'puzzle' | 'store';
+interface ResourceTypeInfo {
+    type: ResourceType;
+    /** Singular display label, e.g. "Skill" (card type caption). */
+    label: string;
+    /** Plural display label, e.g. "Skills" (stat tiles, filters). */
+    pluralLabel: string;
+    /** Icon identifier resolved to a component by the frontend. */
+    icon: ResourceTypeIcon;
     /**
-     * Content of bundled resource files for skills (path → file content).
-     * Only populated for assets of type `skill` that declare `resources` in the envelope.
+     * Colour role name; the frontend resolves it to the plugin-owned
+     * `--devaihub-type-<role>` custom properties (ADR-0008, NOS palette).
      */
-    resourcesContent?: Record<string, string>;
-    /** Path of the .yaml file in the repository */
-    yamlPath: string;
-    /** Path of the .md file in the repository */
-    mdPath: string;
-    repoUrl: string;
-    branch: string;
-    commitSha?: string;
-    installCount: number;
-    syncedAt: string;
-    createdAt: string;
-    updatedAt: string;
+    colorRole: ResourceType;
 }
-interface AiAssetListResponse {
-    items: AiAssetSummary[];
-    totalCount: number;
-    page: number;
-    pageSize: number;
+/**
+ * The typed type→card registry (ADR-0003/ADR-0008): producer vocabulary and
+ * consumer rendering share this single source, so they cannot drift. Adding
+ * a type is one entry here plus one CSS token pair in the frontend.
+ */
+declare const RESOURCE_TYPE_REGISTRY: Record<ResourceType, ResourceTypeInfo>;
+/**
+ * The flat contract the backend returns to the frontend. The frontend never
+ * sees a raw Backstage `Entity` — only this (architecture.md).
+ */
+interface ResourceSummary {
+    entityRef: string;
+    name: string;
+    title?: string;
+    description?: string;
+    tags: string[];
+    type: ResourceType;
+    lifecycle: string;
+    owner?: string;
+    sourceLocation?: string;
+    frameworks: string[];
+    version?: string;
+    kind: string;
+    /** `plugin` dependsOn count; unpopulated until containment lands (issue #32). */
+    childCount?: number;
+    helpText?: string;
+    annotations: Record<string, string>;
+}
+interface ResourceListResponse {
+    items: ResourceSummary[];
 }
-interface AiHubProvider {
-    id: string;
-    type: 'github' | 'bitbucket' | 'azure-devops' | 'gitlab' | 'git';
-    target: string;
-    branch: string;
-    lastSync?: string;
-    lastCommit?: string;
-    status: 'idle' | 'syncing' | 'error';
-    error?: string;
-    assetCount: number;
+/**
+ * The shape of a resource's body (CONTEXT.md: bodies are type-shaped, not
+ * uniformly markdown). Drives detail-panel rendering: markdown is rendered,
+ * json is shown as a copyable code block.
+ */
+type BodyShape = 'markdown' | 'json';
+declare function getBodyShape(type: ResourceType): BodyShape;
+/**
+ * Whether downloading the body delivers the artifact itself. True for the
+ * types whose body IS the installable content (skill files, agent
+ * definition, hook/mcp-config config to merge). False for the pointer-shaped
+ * bodies: a `plugin` installs through its framework
+ * (`/plugin install name@marketplace`) and a `marketplace` is *registered*,
+ * not fetched — for both, a download could only deliver the instructions
+ * doc, misrepresenting itself as the thing (ADR-0009 amendment, ADR-0010).
+ */
+declare function hasDownloadableArtifact(type: ResourceType): boolean;
+/**
+ * Whether copying the body to the clipboard is a meaningful install action.
+ * False only for `marketplace`: its body is an instructions doc, and the
+ * actionable copies (add command, team snippet) each carry their own copy
+ * button — a "Copy content" that delivers the doc misrepresents itself as
+ * the marketplace, mirroring the Download reasoning (ADR-0010). A `plugin`
+ * body keeps copy: it is the canonical per-framework install guidance.
+ */
+declare function hasCopyableBody(type: ResourceType): boolean;
+/**
+ * How a body reaches its install path.
+ *
+ * `drop-in` — the body becomes the file (or directory) at `path`, which is
+ * the resource's own; writing it touches nothing else.
+ *
+ * `merge` — `path` is a shared settings file the user already owns, and the
+ * body is a fragment to merge into it. The distinction is not cosmetic:
+ * following a `merge` target as if it were a `drop-in` overwrites the user's
+ * existing configuration, so the UI must never present the two identically.
+ */
+type InstallMode = 'drop-in' | 'merge';
+interface ResourceInstallTarget {
+    /** Workspace-relative path. */
+    path: string;
+    mode: InstallMode;
 }
-interface AiHubStats {
-    totalAssets: number;
-    byType: Record<AssetType, number>;
-    byTool: Record<string, number>;
-    byProvider: Record<string, number>;
-    lastSync?: string;
+/**
+ * The concrete framework tokens a body can be installed into — `all` is a
+ * wildcard over these, never a destination itself.
+ */
+declare const INSTALLABLE_FRAMEWORKS: readonly ["claude-code", "github-copilot", "google-gemini", "cursor"];
+/**
+ * Where a resource's body installs for one framework, and whether that path
+ * is the body's own file or a settings file to merge into. Returns
+ * `undefined` when the (type, framework) pair has no filesystem convention.
+ */
+declare function getResourceInstallTarget(type: ResourceType, framework: string, name: string): ResourceInstallTarget | undefined;
+/**
+ * The frameworks to show install paths for. An empty list means the resource
+ * declared no compatibility and gets the neutral `default` convention; `all`
+ * is a wildcard and expands to every installable host, so it never collapses
+ * to a single row — or, for types with no `default`, to no rows at all.
+ */
+declare function expandInstallFrameworks(frameworks: string[]): string[];
+/** Frameworks with a marketplace-add concept (Cursor/Gemini have none). */
+declare const MARKETPLACE_CAPABLE_FRAMEWORKS: readonly ["claude-code", "github-copilot"];
+/**
+ * Narrow a resource's declared frameworks to those a given journey can
+ * actually launch. A deep link is a claim about compatibility: offering
+ * "Install in Claude" for a resource that never declared `claude-code` tells
+ * the user something untrue about the resource.
+ *
+ * `all` and an empty list both mean "unrestricted" and expand to every
+ * capable host. Anything else is intersected, so a declared framework with no
+ * handler (Gemini) — or an unknown token — yields no links rather than
+ * silently widening to every host.
+ */
+declare function resolveCapableFrameworks(declared: string[], capable: readonly string[]): string[];
+/**
+ * Derive the `owner/repo` slug from a marketplace's `source-location`.
+ * GitHub URLs only — other hosts return `undefined` (body-only fallback).
+ */
+declare function getMarketplaceRepoSlug(sourceLocation: string | undefined): string | undefined;
+/**
+ * A one-click launcher for an add command: a custom-scheme URL that opens
+ * the host app with the command pre-filled in the prompt box. The host
+ * never auto-executes it — the user reviews and presses Enter — and an
+ * unregistered scheme is a harmless no-op, so these complement the copy
+ * button rather than replace it.
+ */
+interface ResourceDeepLink {
+    /** Host application name; render as "Add in <label>" / "Install in <label>". */
+    label: string;
+    href: string;
 }
-interface AssetListFilter {
-    type?: AssetType;
-    tool?: string;
-    tags?: string[];
-    search?: string;
-    providerId?: string;
-    page?: number;
-    pageSize?: number;
+interface MarketplaceAddCommand {
+    framework: string;
+    command: string;
+    deepLinks: ResourceDeepLink[];
 }
-
-declare const AiToolEnum: z.ZodEnum<["all", "github-copilot", "claude-code", "google-gemini", "cursor"]>;
-declare const AssetTypeEnum: z.ZodEnum<["instruction", "agent", "skill", "workflow"]>;
-/**
- * Schema for the YAML metadata file (.yaml) that acts as an envelope.
- * The actual asset content lives in the referenced .md file.
- */
-declare const AiAssetFrontmatterSchema: z.ZodObject<{
-    /** Path to the .md content file, relative to the .yaml file directory.
-     *  If omitted, the parser falls back to <same-name>.md by convention. */
-    content: z.ZodOptional<z.ZodString>;
-    name: z.ZodString;
-    /** Human-readable display label shown in the UI. Falls back to `name` when omitted. */
-    label: z.ZodOptional<z.ZodString>;
-    description: z.ZodString;
-    type: z.ZodEnum<["instruction", "agent", "skill", "workflow"]>;
-    tools: z.ZodArray<z.ZodEnum<["all", "github-copilot", "claude-code", "google-gemini", "cursor"]>, "many">;
-    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
-    author: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    icon: z.ZodOptional<z.ZodString>;
-    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    updatedAt: z.ZodOptional<z.ZodString>;
-    installPath: z.ZodOptional<z.ZodString>;
-    installPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    resources: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    /** Path to the .md content file, relative to the .yaml file directory.
-     *  If omitted, the parser falls back to <same-name>.md by convention. */
-    content: z.ZodOptional<z.ZodString>;
-    name: z.ZodString;
-    /** Human-readable display label shown in the UI. Falls back to `name` when omitted. */
-    label: z.ZodOptional<z.ZodString>;
-    description: z.ZodString;
-    type: z.ZodEnum<["instruction", "agent", "skill", "workflow"]>;
-    tools: z.ZodArray<z.ZodEnum<["all", "github-copilot", "claude-code", "google-gemini", "cursor"]>, "many">;
-    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
-    author: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    icon: z.ZodOptional<z.ZodString>;
-    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    updatedAt: z.ZodOptional<z.ZodString>;
-    installPath: z.ZodOptional<z.ZodString>;
-    installPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    resources: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    /** Path to the .md content file, relative to the .yaml file directory.
-     *  If omitted, the parser falls back to <same-name>.md by convention. */
-    content: z.ZodOptional<z.ZodString>;
-    name: z.ZodString;
-    /** Human-readable display label shown in the UI. Falls back to `name` when omitted. */
-    label: z.ZodOptional<z.ZodString>;
-    description: z.ZodString;
-    type: z.ZodEnum<["instruction", "agent", "skill", "workflow"]>;
-    tools: z.ZodArray<z.ZodEnum<["all", "github-copilot", "claude-code", "google-gemini", "cursor"]>, "many">;
-    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
-    author: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    icon: z.ZodOptional<z.ZodString>;
-    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    updatedAt: z.ZodOptional<z.ZodString>;
-    installPath: z.ZodOptional<z.ZodString>;
-    installPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    resources: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, z.ZodTypeAny, "passthrough">>;
-type AiAssetFrontmatter = z.infer<typeof AiAssetFrontmatterSchema>;
-
-interface InstallPathOverrides {
-    /** Single path override — applies to all tools when installPaths has no entry for the tool */
-    installPath?: string;
-    /** Per-tool path overrides — highest priority */
-    installPaths?: Record<string, string>;
+/**
+ * The copyable marketplace-add command per compatible framework. `all`,
+ * unknown-only, or empty framework lists expand to every capable framework;
+ * frameworks without a marketplace concept produce no row.
+ *
+ * Claude Code carries a single deep link on the CLI's documented
+ * `claude-cli://open?q=` handler, which opens a Claude Code terminal
+ * session with the command pre-filled regardless of the user's editor.
+ *
+ * Copilot's CLI still has no URI scheme, but Copilot's *other* surface does:
+ * VS Code 1.113 ships `vscode://chat-plugin/add-marketplace?ref=`, which
+ * accepts a plain or base64 `owner/repo` and always shows a confirmation
+ * dialog before registering the marketplace (it also dedupes against the
+ * user's existing entries). So the Copilot row keeps its terminal command for
+ * CLI users *and* gains editor launchers, mirroring how `mcp-config` already
+ * maps `github-copilot` onto the VS Code stable/Insiders pair.
+ */
+declare function getMarketplaceAddCommands(frameworks: string[], repoSlug: string): MarketplaceAddCommand[];
+/** Frameworks with a one-click agent-install handler (Gemini has none). */
+declare const AGENT_LINK_CAPABLE_FRAMEWORKS: readonly ["claude-code", "github-copilot", "cursor"];
+/** Hosts reachable by a generic prompt URI — the only route for skill/hook. */
+declare const PROMPT_LINK_CAPABLE_FRAMEWORKS: readonly ["claude-code", "cursor"];
+/**
+ * One-click launchers for the types with no purpose-built install route —
+ * `skill` and `hook`. Both ride the generic prompt handlers, so the prompt
+ * names the *host's own* install path and respects its install mode: a `merge`
+ * target is asked to be merged into, never overwritten, so a launcher can
+ * never cost the user their existing settings.
+ *
+ * Returns `[]` when the source URL cannot be derived, or for hosts with no
+ * prompt route (Copilot, Gemini) — the path list and copy/download remain.
+ */
+declare function getPromptInstallLinks(type: ResourceType, sourceLocation: string | undefined, name: string, frameworks?: string[]): ResourceDeepLink[];
+/**
+ * Everything a single host needs to install a resource: where the body goes,
+ * the prompt that puts it there, and a launcher when the host has a URI to
+ * launch.
+ *
+ * `link` is absent for hosts with no prompt route — Copilot and Gemini. That
+ * absence is why the step carries `prompt` as text: a host without a URI is
+ * not a host without an install path, and the same instruction that a launcher
+ * would pre-fill can be pasted into that agent by hand. Every declared
+ * framework therefore gets something actionable, not a bare path.
+ */
+interface ResourceInstallStep {
+    framework: string;
+    target: ResourceInstallTarget;
+    /** The install instruction, ready to run in that host's agent. */
+    prompt: string;
+    /** One-click launcher, where the host exposes a generic prompt URI. */
+    link?: ResourceDeepLink;
 }
+declare function getInstallSteps(type: ResourceType, sourceLocation: string | undefined, name: string, frameworks?: string[]): ResourceInstallStep[];
+/** Frameworks with a one-click MCP-install handler (Gemini has none). */
+declare const MCP_LINK_CAPABLE_FRAMEWORKS: readonly ["claude-code", "github-copilot", "cursor"];
 /**
- * Returns the recommended install path for an asset in a given tool's workspace.
- * Resolution order: installPaths[tool] > installPath > built-in convention.
+ * One-click install links for an `agent` resource, restricted to the
+ * resource's own compatible frameworks. VS Code stable and Insiders use the
+ * native `chat-agent/install?url=` handler (the mechanism behind
+ * awesome-copilot's Install buttons) and are Copilot's hosts, so they follow
+ * `github-copilot`: VS Code downloads the file at `url` and asks the user
+ * where to save it. Claude Code uses the `claude-cli://open?q=` handler with
+ * an install prompt pre-filled to the convention path — reviewed and sent by
+ * the user, never auto-executed. All derive from the GitHub blob URL in
+ * `source-location`; anything else returns `[]` (copy/download fallback).
  */
-declare function getInstallPath(type: AssetType, tool: AiTool | string, name: string, overrides?: InstallPathOverrides): string;
+declare function getAgentInstallLinks(sourceLocation: string | undefined, name: string, frameworks?: string[]): ResourceDeepLink[];
+/**
+ * One-click install links for an `mcp-config` resource, derived from its body —
+ * the canonical `.mcp.json` snippet (spec §3.4). VS Code carries a native
+ * `vscode:mcp/install?{json}` handler (Insiders scheme twin), Cursor a
+ * documented `cursor://anysphere.cursor-deeplink/mcp/install` one, and
+ * Claude Code gets a `claude-cli://open?q=` prompt around
+ * `claude mcp add-json` — pre-filled, reviewed, never auto-executed.
+ * Hosts follow the resource's own compatible frameworks: `all`/empty expand
+ * to every capable host, anything else is intersected, so an mcp-config
+ * declaring only Gemini (no handler) gets no links rather than every host's.
+ * A missing, unparseable, or multi-server body returns `[]` (copy fallback) —
+ * the body stays canonical, links are conveniences derived from it.
+ */
+declare function getMcpInstallLinks(frameworks: string[], resourceName: string, bodyContent: string | undefined): ResourceDeepLink[];
+/**
+ * Step two of the journey: how to install a plugin from the marketplace.
+ * `marketplaceName` is the entity name, which the producer contract requires
+ * to equal the `name` in `marketplace.json`.
+ */
+declare function getMarketplaceInstallTemplate(marketplaceName: string): string;
+/**
+ * The `.claude/settings.json` snippet a team commits so collaborators are
+ * prompted to install the marketplace automatically (Claude Code).
+ */
+declare function getMarketplaceTeamSnippet(marketplaceName: string, repoSlug: string): string;
+
 /**
- * Returns install paths for all tools in the asset's tools list.
- * If tools contains 'all', returns paths for every known tool.
+ * Telemetry actions (ADR-0007). All four are stored raw and returned raw by
+ * `GET /telemetry/:ref` as lifetime totals. `view` is recorded when a user
+ * opens a resource, not when a card renders.
  */
-declare function getInstallPathsForAsset(type: AssetType, tools: (AiTool | string)[], name: string, overrides?: InstallPathOverrides): Record<string, string>;
+declare const TelemetryActionEnum: z.ZodEnum<["install", "copy", "download", "view"]>;
+type TelemetryAction = z.infer<typeof TelemetryActionEnum>;
+declare const TelemetryEventInputSchema: z.ZodObject<{
+    ref: z.ZodString;
+    action: z.ZodEnum<["install", "copy", "download", "view"]>;
+    tool: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    ref: string;
+    action: "install" | "copy" | "download" | "view";
+    tool?: string | undefined;
+}, {
+    ref: string;
+    action: "install" | "copy" | "download" | "view";
+    tool?: string | undefined;
+}>;
+type TelemetryEventInput = z.infer<typeof TelemetryEventInputSchema>;
+/** Raw per-action counts for one resource, as returned by `GET /telemetry/:ref`. */
+type TelemetryCounts = Record<TelemetryAction, number>;
 
-export { AiAssetFrontmatterSchema, AiToolEnum, AssetTypeEnum, getInstallPath, getInstallPathsForAsset };
-export type { AiAsset, AiAssetFrontmatter, AiAssetListResponse, AiAssetSummary, AiHubProvider, AiHubStats, AiTool, AssetListFilter, AssetType, InstallPathOverrides };
+export { AGENT_LINK_CAPABLE_FRAMEWORKS, ANNOTATION_COMPATIBLE_FRAMEWORKS, ANNOTATION_HELP, ANNOTATION_VERSION, DEVAIHUB_ANNOTATION_PREFIX, INSTALLABLE_FRAMEWORKS, KNOWN_FRAMEWORKS, MARKETPLACE_CAPABLE_FRAMEWORKS, MCP_LINK_CAPABLE_FRAMEWORKS, PROMPT_LINK_CAPABLE_FRAMEWORKS, RESOURCE_TYPES, RESOURCE_TYPE_REGISTRY, TelemetryActionEnum, TelemetryEventInputSchema, expandInstallFrameworks, getAgentInstallLinks, getBodyShape, getFrameworks, getInstallSteps, getMarketplaceAddCommands, getMarketplaceInstallTemplate, getMarketplaceRepoSlug, getMarketplaceTeamSnippet, getMcpInstallLinks, getPromptInstallLinks, getResourceInstallTarget, hasCopyableBody, hasDownloadableArtifact, isResourceType, normalizeFramework, resolveCapableFrameworks };
+export type { AiResourceEntityLike, BodyShape, FrameworkToken, InstallMode, MarketplaceAddCommand, ResourceDeepLink, ResourceInstallStep, ResourceInstallTarget, ResourceListResponse, ResourceSummary, ResourceType, ResourceTypeIcon, ResourceTypeInfo, TelemetryAction, TelemetryCounts, TelemetryEventInput };

package/dist/index.esm.js

@@ -1,3 +1,3 @@
-export { AiAssetFrontmatterSchema, AiToolEnum, AssetTypeEnum } from './schemas.esm.js';
-export { getInstallPath, getInstallPathsForAsset } from './installPaths.esm.js';
+export { AGENT_LINK_CAPABLE_FRAMEWORKS, ANNOTATION_COMPATIBLE_FRAMEWORKS, ANNOTATION_HELP, ANNOTATION_VERSION, DEVAIHUB_ANNOTATION_PREFIX, INSTALLABLE_FRAMEWORKS, KNOWN_FRAMEWORKS, MARKETPLACE_CAPABLE_FRAMEWORKS, MCP_LINK_CAPABLE_FRAMEWORKS, PROMPT_LINK_CAPABLE_FRAMEWORKS, RESOURCE_TYPES, RESOURCE_TYPE_REGISTRY, expandInstallFrameworks, getAgentInstallLinks, getBodyShape, getFrameworks, getInstallSteps, getMarketplaceAddCommands, getMarketplaceInstallTemplate, getMarketplaceRepoSlug, getMarketplaceTeamSnippet, getMcpInstallLinks, getPromptInstallLinks, getResourceInstallTarget, hasCopyableBody, hasDownloadableArtifact, isResourceType, normalizeFramework, resolveCapableFrameworks } from './resources.esm.js';
+export { TelemetryActionEnum, TelemetryEventInputSchema } from './telemetry.esm.js';
 //# sourceMappingURL=index.esm.js.map