Entity-Provider SDK — Types, Interfaces, Annotation Validation (issue 2 of 29)

[gabemontero]

Labels: ready-to-code
Dependencies: None
RHIDP Stories: RHIDP-15255, RHIDP-15259, RHIDP-15303
Feature: RHDHPLAN-1507 — Epic RHIDP-15258

Create the @red-hat-developer-hub/backstage-plugin-boost-entity-provider-sdk package with the AI Asset annotation scheme (rhdh.io/ai-asset-category, rhdh.io/ai-asset-version, rhdh.io/ai-asset-source), version normalization utility, CatalogProcessor validator, AIAssetEntityProvider interface definition, Neo4jSyncAdapter interface, and SkillBundleMetadata type. This issue establishes all type contracts — the delta sync framework and package publishing are in Issue 8.

Tasks

From openspec/changes/ai-catalog-entity-model/tasks.md group 1 (RHIDP-15255):

• 1.1 Define rhdh.io/ai-asset-category annotation constant and allowed values enum (agent, skill, rule, skill-bundle, mcp-server, ai-model, model-server)
• 1.2 Define rhdh.io/ai-asset-version annotation constant
• 1.3 Define rhdh.io/ai-asset-source annotation constant
• 1.4 Implement normalizeAIAssetVersion(sourceVersion) utility with all four normalization rules
• 1.5 Add unit tests for normalizeAIAssetVersion()
• 1.6 Implement CatalogProcessor validator rejecting entities with missing/invalid annotations
• 1.7 Add unit tests for CatalogProcessor validator

From openspec/changes/ai-catalog-entity-model/tasks.md group 2 (RHIDP-15259, RHIDP-15260 — package+interface):

• 2.1 Create @red-hat-developer-hub/backstage-plugin-boost-entity-provider-sdk package with package.json, tsconfig.json, README.md
• 2.2 Define AIAssetEntityProvider TypeScript interface with required methods: connect(), * entities(), getProviderName(), getProviderId()
• 2.3 Define optional delta(cursor?: string) method for incremental sync pattern
• 2.4 Export annotation constants: AI_ASSET_CATEGORY_ANNOTATION, AI_ASSET_VERSION_ANNOTATION, AI_ASSET_SOURCE_ANNOTATION
• 2.5 Implement validateAIAssetEntity(entity) utility throwing on missing/invalid annotations
• 2.6 Add unit tests for validateAIAssetEntity()

From openspec/changes/ai-catalog-entity-model/tasks.md group 3 (RHIDP-15303):

• 3.1 Define Neo4jSyncAdapter TypeScript interface with methods: createNode(), updateNode(), deleteNode(), createRelationship()
• 3.2 Define RelationshipType union type with constants: DEPENDS_ON, USES_TOOL, BELONGS_TO, SIMILAR_TO, IMPLEMENTED_BY, INCLUDES
• 3.3 Export Neo4jSyncAdapter interface from SDK package
• 3.4 Add JSDoc documentation to interface

From openspec/changes/ai-catalog-entity-model/tasks.md group 4 (RHIDP-15303):

• 4.1 Define SkillBundleMetadata TypeScript type with fields
• 4.2 Export SkillBundleMetadata type from SDK package
• 4.3 Add JSDoc documentation with example skillcard.yaml structure

Specifications

• openspec/changes/ai-catalog-entity-model/specs/annotation-scheme/spec.md
• openspec/changes/ai-catalog-entity-model/specs/entity-provider-sdk/spec.md

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 7:59 PM UTC · Completed 8:03 PM UTC
Commit: e03b281 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: High · Category: Feature

This issue is well-specified and ready for implementation. It establishes the foundational type contracts for the AI catalog entity model SDK, with 18 subtasks across 4 groups. Both referenced spec files exist in the repository.

Problem

The boost workspace needs a shared @boost/entity-provider-sdk package defining annotation constants, validation utilities, and TypeScript interfaces that all downstream connectors and the delta sync framework depend on.

Recommended Approach

1. Read behavioral specs at openspec/changes/ai-catalog-entity-model/specs/annotation-scheme/spec.md and entity-provider-sdk/spec.md
2. Scaffold the package (package.json, tsconfig.json, README.md)
3. Define annotation constants (AI_ASSET_CATEGORY_ANNOTATION, AI_ASSET_VERSION_ANNOTATION, AI_ASSET_SOURCE_ANNOTATION) and the AIAssetCategory enum
4. Implement normalizeAIAssetVersion() with all four normalization rules (semver pass-through, date-based, commit hash, fallback)
5. Implement CatalogProcessor validator gated to entities carrying any rhdh.io/ai-asset-* annotation
6. Define AIAssetEntityProvider interface with connect(), entities() generator, getProviderName(), getProviderId(), and optional delta() method
7. Implement validateAIAssetEntity() utility throwing on missing/invalid annotations
8. Define Neo4jSyncAdapter interface with CRUD methods and RelationshipType union
9. Define SkillBundleMetadata type with JSDoc and skillcard.yaml example

Per workspace conventions (AGENTS.md), use Zod schemas as the single source of truth for validation, with TypeScript types inferred from Zod.

Proposed Test Cases

normalizeAIAssetVersion():
  - '1.2.3' → '1.2.3' (semver pass-through)
  - '2.0.0-beta.1' → '2.0.0-beta.1' (pre-release pass-through)
  - '20260708' → '0.0.0-20260708' (date-based)
  - '2026-07-08' → '0.0.0-20260708' (date with dashes)
  - 'a1b2c3d' → '0.0.0-a1b2c3d' (commit hash)
  - 'unknown-format' → '0.0.0-unknown' (fallback + warning)

CatalogProcessor validator:
  - Accepts valid AI asset entity
  - Rejects missing category when ai-asset annotations present
  - Rejects invalid category value
  - Ignores entities without any rhdh.io/ai-asset-* annotations

validateAIAssetEntity():
  - Throws on missing/invalid category, version, or source
  - Passes for fully valid entity

Dependencies

This issue declares no blocking dependencies and focuses on type contracts only. The runtime delta sync framework and package publishing are scoped to issue #4046. While the full SDK scope (RHIDP-15260) has cross-connector dependencies on #4039 (CA bundle, fault isolation, config validation), the type-contract work scoped here can proceed independently.

Previous run

Triage Summary

Severity: High · Category: Feature

This issue is well-specified and ready for implementation. It establishes the foundational type contracts for the AI catalog entity model SDK, with 18 subtasks across 4 groups.

Problem

The boost workspace needs a shared @boost/entity-provider-sdk package defining annotation constants, validation utilities, and TypeScript interfaces that all downstream connectors and the delta sync framework depend on.

Recommended Approach

1. Scaffold the package (package.json, tsconfig.json, README.md)
2. Define annotation constants (AI_ASSET_CATEGORY_ANNOTATION, AI_ASSET_VERSION_ANNOTATION, AI_ASSET_SOURCE_ANNOTATION) and the AIAssetCategory enum
3. Implement normalizeAIAssetVersion() with all four normalization rules (semver pass-through, date-based, commit hash, fallback)
4. Implement CatalogProcessor validator gated to entities carrying any rhdh.io/ai-asset-* annotation
5. Define AIAssetEntityProvider interface with connect(), entities() generator, getProviderName(), getProviderId(), and optional delta() method
6. Implement validateAIAssetEntity() utility throwing on missing/invalid annotations
7. Define Neo4jSyncAdapter interface with CRUD methods and RelationshipType union
8. Define SkillBundleMetadata type with JSDoc and skillcard.yaml example

Per workspace conventions, use Zod schemas as the single source of truth for validation, with TypeScript types inferred from Zod.

Proposed Test Cases

normalizeAIAssetVersion():
  - '1.2.3' → '1.2.3' (semver pass-through)
  - '2.0.0-beta.1' → '2.0.0-beta.1' (pre-release pass-through)
  - '20260708' → '0.0.0-20260708' (date-based)
  - '2026-07-08' → '0.0.0-20260708' (date with dashes)
  - 'a1b2c3d' → '0.0.0-a1b2c3d' (commit hash)
  - 'unknown-format' → '0.0.0-unknown' (fallback + warning)

CatalogProcessor validator:
  - Accepts valid AI asset entity
  - Rejects missing category when ai-asset annotations present
  - Rejects invalid category value
  - Ignores entities without any rhdh.io/ai-asset-* annotations

validateAIAssetEntity():
  - Throws on missing/invalid category, version, or source
  - Passes for fully valid entity

Dependencies

This issue declares no blocking dependencies and focuses on type contracts only. The runtime integration with shared infrastructure (#4039) and package publishing are scoped to issue #4046.

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 7:32 PM UTC · Completed 7:37 PM UTC
Commit: 1b270c9 · View workflow run →