@nospt/plugin-dev-ai-hub-common 0.3.1 → 1.0.0-rc1

package/README.md

@@ -0,0 +1,53 @@
+# @nospt/plugin-dev-ai-hub-common
+
+Isomorphic contracts shared by the **Dev AI Hub** frontend and backend plugins.
+
+> **Requires Backstage 1.51 or later.** The `AiResource` kind comes from Backstage's own alpha catalog module, which is not available before that.
+
+**You do not install this package directly.** It arrives as a dependency of [`@nospt/plugin-dev-ai-hub`](https://www.npmjs.com/package/@nospt/plugin-dev-ai-hub) and [`@nospt/plugin-dev-ai-hub-backend`](https://www.npmjs.com/package/@nospt/plugin-dev-ai-hub-backend), and the three publish in lockstep at the same version.
+
+## Why it exists
+
+A contract duplicated across two packages is a contract that will drift. Anything the frontend and backend must agree on lives here exactly once, and neither plugin imports the other.
+
+It is genuinely isomorphic — no Node-only and no browser-only code — which is why the same package can back both halves.
+
+## The main contract
+
+`ResourceSummary` is the flat shape the backend serves and the frontend consumes. The frontend never sees a raw catalog `Entity`; this is the whole of what it knows about a resource.
+
+```typescript
+interface ResourceSummary {
+  entityRef: string; // "airesource:default/azure-devops-cli"
+  name: string;
+  title?: string;
+  description?: string;
+  tags: string[];
+  type: ResourceType;
+  lifecycle: string;
+  owner?: string;
+  sourceLocation?: string; // absent → browsable, not installable
+  frameworks: string[]; // "claude-code", "github-copilot", …
+  version?: string;
+  kind: string;
+  childCount?: number; // unpopulated until containment lands
+  helpText?: string;
+  annotations: Record<string, string>;
+}
+```
+
+`toResourceSummary(entity)` is the `Entity` → `ResourceSummary` mapping, exported here so the backend router and the test fixtures cannot disagree about it.
+
+## Also in here
+
+- **The `ResourceType` vocabulary** — `skill`, `agent`, `hook`, `mcp-config`, `plugin`, `marketplace` — and the rules derived from it: which body shape a type renders as (`mcp-config` is JSON, the rest markdown), whether its body is a downloadable artifact or merely a pointer, and its per-framework install paths.
+- **Framework tokens and normalisation**, so `claude-code` means the same thing on both sides.
+- **Telemetry schemas** for the event contract.
+
+## Full documentation
+
+See the [repository README](https://github.com/nosportugal/backstage-plugin-dev-ai-hub#readme) for setup, and [`docs/AIRESOURCE-SPEC.md`](https://github.com/nosportugal/backstage-plugin-dev-ai-hub/blob/main-nos/docs/AIRESOURCE-SPEC.md) for the full `AiResource` entity spec.
+
+## License
+
+Apache-2.0

package/dist/index.cjs.js

@@ -2,6 +2,7 @@
 
 var resources = require('./resources.cjs.js');
 var telemetry = require('./telemetry.cjs.js');
+var toResourceSummary = require('./toResourceSummary.cjs.js');
 
 
 
@@ -36,4 +37,5 @@ exports.normalizeFramework = resources.normalizeFramework;
 exports.resolveCapableFrameworks = resources.resolveCapableFrameworks;
 exports.TelemetryActionEnum = telemetry.TelemetryActionEnum;
 exports.TelemetryEventInputSchema = telemetry.TelemetryEventInputSchema;
+exports.toResourceSummary = toResourceSummary.toResourceSummary;
 //# 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,4 +1,5 @@
 import { z } from 'zod';
+import { Entity } from '@backstage/catalog-model';
 
 /**
  * The v2 read contract: AiResource vocabulary, the flat ResourceSummary
@@ -318,5 +319,19 @@ 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 { 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 };
+/**
+ * Map a catalog AiResource entity to the flat contract served to the
+ * frontend. Returns undefined for entities with an unsupported `spec.type`,
+ * which are silently dropped (ADR-0003).
+ *
+ * Lives in `common` rather than the backend because it is pure and
+ * isomorphic — `Entity` in, `ResourceSummary` out — and both the backend
+ * router and the frontend's e2e fixtures need it to agree. The e2e suite
+ * builds its mock `GET /resources` payload by running the real examples in
+ * `examples/catalog/` through this function, so a change to the mapping
+ * cannot silently diverge from what the tests assert against.
+ */
+declare function toResourceSummary(entity: Entity): ResourceSummary | undefined;
+
+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, toResourceSummary };
 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,4 @@
 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';
+export { toResourceSummary } from './toResourceSummary.esm.js';
 //# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

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

package/dist/toResourceSummary.cjs.js

@@ -0,0 +1,31 @@
+'use strict';
+
+var catalogModel = require('@backstage/catalog-model');
+var resources = require('./resources.cjs.js');
+
+function toResourceSummary(entity) {
+  const type = entity.spec?.type;
+  if (!resources.isResourceType(type)) {
+    return void 0;
+  }
+  const annotations = entity.metadata.annotations ?? {};
+  return {
+    entityRef: catalogModel.stringifyEntityRef(entity),
+    name: entity.metadata.name,
+    title: entity.metadata.title,
+    description: entity.metadata.description,
+    tags: entity.metadata.tags ?? [],
+    type,
+    lifecycle: typeof entity.spec?.lifecycle === "string" ? entity.spec.lifecycle : "",
+    owner: typeof entity.spec?.owner === "string" ? entity.spec.owner : void 0,
+    sourceLocation: annotations[catalogModel.ANNOTATION_SOURCE_LOCATION],
+    frameworks: resources.getFrameworks(entity),
+    version: annotations[resources.ANNOTATION_VERSION],
+    kind: entity.kind,
+    helpText: annotations[resources.ANNOTATION_HELP],
+    annotations
+  };
+}
+
+exports.toResourceSummary = toResourceSummary;
+//# sourceMappingURL=toResourceSummary.cjs.js.map

package/dist/toResourceSummary.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toResourceSummary.cjs.js","sources":["../src/toResourceSummary.ts"],"sourcesContent":["import {\n  ANNOTATION_SOURCE_LOCATION,\n  stringifyEntityRef,\n  type Entity,\n} from '@backstage/catalog-model';\nimport {\n  ANNOTATION_HELP,\n  ANNOTATION_VERSION,\n  getFrameworks,\n  isResourceType,\n  type ResourceSummary,\n} from './resources';\n\n/**\n * Map a catalog AiResource entity to the flat contract served to the\n * frontend. Returns undefined for entities with an unsupported `spec.type`,\n * which are silently dropped (ADR-0003).\n *\n * Lives in `common` rather than the backend because it is pure and\n * isomorphic — `Entity` in, `ResourceSummary` out — and both the backend\n * router and the frontend's e2e fixtures need it to agree. The e2e suite\n * builds its mock `GET /resources` payload by running the real examples in\n * `examples/catalog/` through this function, so a change to the mapping\n * cannot silently diverge from what the tests assert against.\n */\nexport function toResourceSummary(entity: Entity): ResourceSummary | undefined {\n  const type = entity.spec?.type;\n  if (!isResourceType(type)) {\n    return undefined;\n  }\n\n  const annotations = entity.metadata.annotations ?? {};\n\n  return {\n    entityRef: stringifyEntityRef(entity),\n    name: entity.metadata.name,\n    title: entity.metadata.title,\n    description: entity.metadata.description,\n    tags: entity.metadata.tags ?? [],\n    type,\n    lifecycle:\n      typeof entity.spec?.lifecycle === 'string' ? entity.spec.lifecycle : '',\n    owner:\n      typeof entity.spec?.owner === 'string' ? entity.spec.owner : undefined,\n    sourceLocation: annotations[ANNOTATION_SOURCE_LOCATION],\n    frameworks: getFrameworks(entity),\n    version: annotations[ANNOTATION_VERSION],\n    kind: entity.kind,\n    helpText: annotations[ANNOTATION_HELP],\n    annotations,\n  };\n}\n"],"names":["isResourceType","stringifyEntityRef","ANNOTATION_SOURCE_LOCATION","getFrameworks","ANNOTATION_VERSION","ANNOTATION_HELP"],"mappings":";;;;;AAyBO,SAAS,kBAAkB,MAAA,EAA6C;AAC7E,EAAA,MAAM,IAAA,GAAO,OAAO,IAAA,EAAM,IAAA;AAC1B,EAAA,IAAI,CAACA,wBAAA,CAAe,IAAI,CAAA,EAAG;AACzB,IAAA,OAAO,MAAA;AAAA,EACT;AAEA,EAAA,MAAM,WAAA,GAAc,MAAA,CAAO,QAAA,CAAS,WAAA,IAAe,EAAC;AAEpD,EAAA,OAAO;AAAA,IACL,SAAA,EAAWC,gCAAmB,MAAM,CAAA;AAAA,IACpC,IAAA,EAAM,OAAO,QAAA,CAAS,IAAA;AAAA,IACtB,KAAA,EAAO,OAAO,QAAA,CAAS,KAAA;AAAA,IACvB,WAAA,EAAa,OAAO,QAAA,CAAS,WAAA;AAAA,IAC7B,IAAA,EAAM,MAAA,CAAO,QAAA,CAAS,IAAA,IAAQ,EAAC;AAAA,IAC/B,IAAA;AAAA,IACA,SAAA,EACE,OAAO,MAAA,CAAO,IAAA,EAAM,cAAc,QAAA,GAAW,MAAA,CAAO,KAAK,SAAA,GAAY,EAAA;AAAA,IACvE,KAAA,EACE,OAAO,MAAA,CAAO,IAAA,EAAM,UAAU,QAAA,GAAW,MAAA,CAAO,KAAK,KAAA,GAAQ,MAAA;AAAA,IAC/D,cAAA,EAAgB,YAAYC,uCAA0B,CAAA;AAAA,IACtD,UAAA,EAAYC,wBAAc,MAAM,CAAA;AAAA,IAChC,OAAA,EAAS,YAAYC,4BAAkB,CAAA;AAAA,IACvC,MAAM,MAAA,CAAO,IAAA;AAAA,IACb,QAAA,EAAU,YAAYC,yBAAe,CAAA;AAAA,IACrC;AAAA,GACF;AACF;;;;"}

package/dist/toResourceSummary.esm.js

@@ -0,0 +1,29 @@
+import { ANNOTATION_SOURCE_LOCATION, stringifyEntityRef } from '@backstage/catalog-model';
+import { isResourceType, ANNOTATION_HELP, ANNOTATION_VERSION, getFrameworks } from './resources.esm.js';
+
+function toResourceSummary(entity) {
+  const type = entity.spec?.type;
+  if (!isResourceType(type)) {
+    return void 0;
+  }
+  const annotations = entity.metadata.annotations ?? {};
+  return {
+    entityRef: stringifyEntityRef(entity),
+    name: entity.metadata.name,
+    title: entity.metadata.title,
+    description: entity.metadata.description,
+    tags: entity.metadata.tags ?? [],
+    type,
+    lifecycle: typeof entity.spec?.lifecycle === "string" ? entity.spec.lifecycle : "",
+    owner: typeof entity.spec?.owner === "string" ? entity.spec.owner : void 0,
+    sourceLocation: annotations[ANNOTATION_SOURCE_LOCATION],
+    frameworks: getFrameworks(entity),
+    version: annotations[ANNOTATION_VERSION],
+    kind: entity.kind,
+    helpText: annotations[ANNOTATION_HELP],
+    annotations
+  };
+}
+
+export { toResourceSummary };
+//# sourceMappingURL=toResourceSummary.esm.js.map

package/dist/toResourceSummary.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toResourceSummary.esm.js","sources":["../src/toResourceSummary.ts"],"sourcesContent":["import {\n  ANNOTATION_SOURCE_LOCATION,\n  stringifyEntityRef,\n  type Entity,\n} from '@backstage/catalog-model';\nimport {\n  ANNOTATION_HELP,\n  ANNOTATION_VERSION,\n  getFrameworks,\n  isResourceType,\n  type ResourceSummary,\n} from './resources';\n\n/**\n * Map a catalog AiResource entity to the flat contract served to the\n * frontend. Returns undefined for entities with an unsupported `spec.type`,\n * which are silently dropped (ADR-0003).\n *\n * Lives in `common` rather than the backend because it is pure and\n * isomorphic — `Entity` in, `ResourceSummary` out — and both the backend\n * router and the frontend's e2e fixtures need it to agree. The e2e suite\n * builds its mock `GET /resources` payload by running the real examples in\n * `examples/catalog/` through this function, so a change to the mapping\n * cannot silently diverge from what the tests assert against.\n */\nexport function toResourceSummary(entity: Entity): ResourceSummary | undefined {\n  const type = entity.spec?.type;\n  if (!isResourceType(type)) {\n    return undefined;\n  }\n\n  const annotations = entity.metadata.annotations ?? {};\n\n  return {\n    entityRef: stringifyEntityRef(entity),\n    name: entity.metadata.name,\n    title: entity.metadata.title,\n    description: entity.metadata.description,\n    tags: entity.metadata.tags ?? [],\n    type,\n    lifecycle:\n      typeof entity.spec?.lifecycle === 'string' ? entity.spec.lifecycle : '',\n    owner:\n      typeof entity.spec?.owner === 'string' ? entity.spec.owner : undefined,\n    sourceLocation: annotations[ANNOTATION_SOURCE_LOCATION],\n    frameworks: getFrameworks(entity),\n    version: annotations[ANNOTATION_VERSION],\n    kind: entity.kind,\n    helpText: annotations[ANNOTATION_HELP],\n    annotations,\n  };\n}\n"],"names":[],"mappings":";;;AAyBO,SAAS,kBAAkB,MAAA,EAA6C;AAC7E,EAAA,MAAM,IAAA,GAAO,OAAO,IAAA,EAAM,IAAA;AAC1B,EAAA,IAAI,CAAC,cAAA,CAAe,IAAI,CAAA,EAAG;AACzB,IAAA,OAAO,MAAA;AAAA,EACT;AAEA,EAAA,MAAM,WAAA,GAAc,MAAA,CAAO,QAAA,CAAS,WAAA,IAAe,EAAC;AAEpD,EAAA,OAAO;AAAA,IACL,SAAA,EAAW,mBAAmB,MAAM,CAAA;AAAA,IACpC,IAAA,EAAM,OAAO,QAAA,CAAS,IAAA;AAAA,IACtB,KAAA,EAAO,OAAO,QAAA,CAAS,KAAA;AAAA,IACvB,WAAA,EAAa,OAAO,QAAA,CAAS,WAAA;AAAA,IAC7B,IAAA,EAAM,MAAA,CAAO,QAAA,CAAS,IAAA,IAAQ,EAAC;AAAA,IAC/B,IAAA;AAAA,IACA,SAAA,EACE,OAAO,MAAA,CAAO,IAAA,EAAM,cAAc,QAAA,GAAW,MAAA,CAAO,KAAK,SAAA,GAAY,EAAA;AAAA,IACvE,KAAA,EACE,OAAO,MAAA,CAAO,IAAA,EAAM,UAAU,QAAA,GAAW,MAAA,CAAO,KAAK,KAAA,GAAQ,MAAA;AAAA,IAC/D,cAAA,EAAgB,YAAY,0BAA0B,CAAA;AAAA,IACtD,UAAA,EAAY,cAAc,MAAM,CAAA;AAAA,IAChC,OAAA,EAAS,YAAY,kBAAkB,CAAA;AAAA,IACvC,MAAM,MAAA,CAAO,IAAA;AAAA,IACb,QAAA,EAAU,YAAY,eAAe,CAAA;AAAA,IACrC;AAAA,GACF;AACF;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nospt/plugin-dev-ai-hub-common",
-  "version": "0.3.1",
+  "version": "1.0.0-rc1",
   "description": "Common types and schemas for Dev AI Hub",
   "license": "Apache-2.0",
   "main": "./dist/index.cjs.js",
@@ -34,13 +34,13 @@
     "pluginPackages": [
       "@nospt/plugin-dev-ai-hub",
       "@nospt/plugin-dev-ai-hub-backend",
-      "@nospt/plugin-dev-ai-hub-common",
-      "@nospt/plugin-dev-ai-hub-node"
+      "@nospt/plugin-dev-ai-hub-common"
     ]
   },
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "backstage-cli package build",
@@ -52,6 +52,7 @@
     "tsc": "tsc --noEmit"
   },
   "dependencies": {
+    "@backstage/catalog-model": "^1.9.0",
     "zod": "^3.22.0"
   },
   "devDependencies": {