diff --git a/.changeset/add-ai-resource-entity-model.md b/.changeset/add-ai-resource-entity-model.md index 8c3356734b..6fcdb79a53 100644 --- a/.changeset/add-ai-resource-entity-model.md +++ b/.changeset/add-ai-resource-entity-model.md @@ -1,5 +1,6 @@ --- '@backstage/plugin-catalog-backend-module-ai-model': minor +'@backstage/catalog-model': minor --- -Introduced the `AiResource` catalog entity kind as an opt-in backend module. Install this module to register support for `AiResource` entities in your catalog, used to represent contextual information consumed by AI coding tools such as skills and rules. +Introduced the `AiResource` catalog entity kind. Entity types, validators, type guards, and the model layer are exported from `@backstage/catalog-model/alpha`. Install `@backstage/plugin-catalog-backend-module-ai-model` in your backend to register the kind with the catalog. diff --git a/packages/catalog-model/report-alpha.api.md b/packages/catalog-model/report-alpha.api.md index 7483d0b6a6..550a79c45c 100644 --- a/packages/catalog-model/report-alpha.api.md +++ b/packages/catalog-model/report-alpha.api.md @@ -3,13 +3,39 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts -import type { Entity } from '@backstage/catalog-model'; +import type { Entity as Entity_2 } from '@backstage/catalog-model'; import { JsonObject } from '@backstage/types'; import { JsonValue } from '@backstage/types'; import { SerializedError } from '@backstage/errors'; // @alpha -export interface AlphaEntity extends Entity { +export const aiResourceEntityModel: CatalogModelLayer; + +// @alpha +export type AiResourceEntityV1alpha1 = + | AiResourceEntityV1alpha1Default + | SkillAiResourceEntityV1alpha1; + +// @alpha +export interface AiResourceEntityV1alpha1Default extends Entity { + // (undocumented) + apiVersion: 'backstage.io/v1alpha1'; + // (undocumented) + kind: 'AiResource'; + // (undocumented) + spec: { + type: string; + lifecycle: string; + owner: string; + system?: string; + }; +} + +// @alpha +export const aiResourceEntityV1alpha1Validator: KindValidator; + +// @alpha +export interface AlphaEntity extends Entity_2 { status?: EntityStatus; } @@ -400,6 +426,43 @@ export function createCatalogModelLayerBuilder(options: { // @alpha export const defaultCatalogEntityModel: CatalogModelLayer; +// @public +export type Entity = { + apiVersion: string; + kind: string; + metadata: EntityMeta; + spec?: JsonObject; + relations?: EntityRelation[]; +}; + +// @public +export type EntityLink = { + url: string; + title?: string; + icon?: string; + type?: string; +}; + +// @public +export type EntityMeta = JsonObject & { + uid?: string; + etag?: string; + name: string; + namespace?: string; + title?: string; + description?: string; + labels?: Record; + annotations?: Record; + tags?: string[]; + links?: EntityLink[]; +}; + +// @public +export type EntityRelation = { + type: string; + targetRef: string; +}; + // @alpha export type EntityStatus = { items?: EntityStatusItem[]; @@ -416,5 +479,42 @@ export type EntityStatusItem = { // @alpha export type EntityStatusLevel = 'info' | 'warning' | 'error'; +// @alpha +export const isAiResourceEntity: ( + entity: Entity, +) => entity is AiResourceEntityV1alpha1; + +// @alpha +export const isSkillAiResourceEntity: ( + entity: Entity, +) => entity is SkillAiResourceEntityV1alpha1; + +// @public +export type KindValidator = { + check(entity: Entity): Promise; +}; + +// @alpha +export interface SkillAiResourceEntityV1alpha1 extends Entity { + // (undocumented) + apiVersion: 'backstage.io/v1alpha1'; + // (undocumented) + kind: 'AiResource'; + // (undocumented) + spec: { + type: 'skill'; + lifecycle: string; + owner: string; + system?: string; + disciplines?: string[]; + categories?: string[]; + agents?: string[]; + dependsOn?: string[]; + }; +} + +// @alpha +export const skillAiResourceEntityV1alpha1Validator: KindValidator; + // (No @packageDocumentation comment for this package) ``` diff --git a/packages/catalog-model/src/alpha.ts b/packages/catalog-model/src/alpha.ts index 9381d92329..d7c7399865 100644 --- a/packages/catalog-model/src/alpha.ts +++ b/packages/catalog-model/src/alpha.ts @@ -14,11 +14,30 @@ * limitations under the License. */ +export type { + Entity, + EntityLink, + EntityMeta, + EntityRelation, +} from './entity/Entity'; +export type { KindValidator } from './kinds/types'; export type { AlphaEntity } from './entity/AlphaEntity'; export type { EntityStatus, EntityStatusItem, EntityStatusLevel, } from './entity/EntityStatus'; +export type { + AiResourceEntityV1alpha1, + AiResourceEntityV1alpha1Default, + SkillAiResourceEntityV1alpha1, +} from './kinds/AiResourceEntityV1alpha1'; +export { + aiResourceEntityV1alpha1Validator, + skillAiResourceEntityV1alpha1Validator, + isAiResourceEntity, + isSkillAiResourceEntity, + aiResourceEntityModel, +} from './kinds/AiResourceEntityV1alpha1'; export * from './model'; export { defaultCatalogEntityModel } from './model/defaultCatalogEntityModel'; diff --git a/plugins/catalog-backend-module-ai-model/src/AiResourceEntityV1alpha1.test.ts b/packages/catalog-model/src/kinds/AiResourceEntityV1alpha1.test.ts similarity index 99% rename from plugins/catalog-backend-module-ai-model/src/AiResourceEntityV1alpha1.test.ts rename to packages/catalog-model/src/kinds/AiResourceEntityV1alpha1.test.ts index 308dc1517a..aa75b414c5 100644 --- a/plugins/catalog-backend-module-ai-model/src/AiResourceEntityV1alpha1.test.ts +++ b/packages/catalog-model/src/kinds/AiResourceEntityV1alpha1.test.ts @@ -14,7 +14,7 @@ * limitations under the License. */ -import type { Entity } from '@backstage/catalog-model'; +import type { Entity } from '../entity/Entity'; import { type AiResourceEntityV1alpha1Default, type SkillAiResourceEntityV1alpha1, diff --git a/plugins/catalog-backend-module-ai-model/src/AiResourceEntityV1alpha1.ts b/packages/catalog-model/src/kinds/AiResourceEntityV1alpha1.ts similarity index 90% rename from plugins/catalog-backend-module-ai-model/src/AiResourceEntityV1alpha1.ts rename to packages/catalog-model/src/kinds/AiResourceEntityV1alpha1.ts index dac2c3c421..53fa20d17a 100644 --- a/plugins/catalog-backend-module-ai-model/src/AiResourceEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/AiResourceEntityV1alpha1.ts @@ -14,20 +14,18 @@ * limitations under the License. */ -import { - type Entity, - entityKindSchemaValidator, - type KindValidator, -} from '@backstage/catalog-model'; -import { createCatalogModelLayer } from '@backstage/catalog-model/alpha'; +import { createCatalogModelLayer } from '../model/createCatalogModelLayer'; +import type { Entity } from '../entity/Entity'; +import { entityKindSchemaValidator } from '../validation'; +import type { KindValidator } from './types'; import type { JsonObject } from '@backstage/types'; -import defaultJsonSchema from './schema/AiResource.v1alpha1.schema.json'; -import skillJsonSchema from './schema/AiResource.v1alpha1.skill.schema.json'; +import defaultJsonSchema from '../schema/kinds/AiResource.v1alpha1.schema.json'; +import skillJsonSchema from '../schema/kinds/AiResource.v1alpha1.skill.schema.json'; /** * Default AiResource entity for types that don't have a structured spec. * - * @public + * @alpha */ export interface AiResourceEntityV1alpha1Default extends Entity { apiVersion: 'backstage.io/v1alpha1'; @@ -44,7 +42,7 @@ export interface AiResourceEntityV1alpha1Default extends Entity { * AiResource entity with spec.type 'skill'. Represents reusable contextual * knowledge consumed by AI coding tools. * - * @public + * @alpha */ export interface SkillAiResourceEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1'; @@ -65,7 +63,7 @@ export interface SkillAiResourceEntityV1alpha1 extends Entity { * Backstage catalog AiResource kind Entity. Represents contextual information * consumed by AI coding tools, such as skills and rules. * - * @public + * @alpha */ export type AiResourceEntityV1alpha1 = | AiResourceEntityV1alpha1Default @@ -76,7 +74,7 @@ const defaultValidator = entityKindSchemaValidator(defaultJsonSchema); /** * Entity data validator for the default {@link AiResourceEntityV1alpha1}. * - * @public + * @alpha */ export const aiResourceEntityV1alpha1Validator: KindValidator = { async check(data: Entity) { @@ -89,7 +87,7 @@ const skillValidator = entityKindSchemaValidator(skillJsonSchema); /** * Entity data validator for {@link SkillAiResourceEntityV1alpha1}. * - * @public + * @alpha */ export const skillAiResourceEntityV1alpha1Validator: KindValidator = { async check(data: Entity) { @@ -100,7 +98,7 @@ export const skillAiResourceEntityV1alpha1Validator: KindValidator = { /** * Type guard for {@link AiResourceEntityV1alpha1}. * - * @public + * @alpha */ export const isAiResourceEntity = ( entity: Entity, @@ -110,7 +108,7 @@ export const isAiResourceEntity = ( /** * Type guard for {@link SkillAiResourceEntityV1alpha1}. * - * @public + * @alpha */ export const isSkillAiResourceEntity = ( entity: Entity, diff --git a/plugins/catalog-backend-module-ai-model/src/schema/AiResource.v1alpha1.schema.json b/packages/catalog-model/src/schema/kinds/AiResource.v1alpha1.schema.json similarity index 100% rename from plugins/catalog-backend-module-ai-model/src/schema/AiResource.v1alpha1.schema.json rename to packages/catalog-model/src/schema/kinds/AiResource.v1alpha1.schema.json diff --git a/plugins/catalog-backend-module-ai-model/src/schema/AiResource.v1alpha1.skill.schema.json b/packages/catalog-model/src/schema/kinds/AiResource.v1alpha1.skill.schema.json similarity index 100% rename from plugins/catalog-backend-module-ai-model/src/schema/AiResource.v1alpha1.skill.schema.json rename to packages/catalog-model/src/schema/kinds/AiResource.v1alpha1.skill.schema.json diff --git a/plugins/catalog-backend-module-ai-model/catalog-info.yaml b/plugins/catalog-backend-module-ai-model/catalog-info.yaml index a99fca43c9..a9b022ecb5 100644 --- a/plugins/catalog-backend-module-ai-model/catalog-info.yaml +++ b/plugins/catalog-backend-module-ai-model/catalog-info.yaml @@ -2,7 +2,7 @@ apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: backstage-plugin-catalog-backend-module-ai-model - title: "@backstage/plugin-catalog-backend-module-ai-model" + title: '@backstage/plugin-catalog-backend-module-ai-model' description: Adds support for the AIResource entity kind to the catalog backend plugin. spec: lifecycle: experimental diff --git a/plugins/catalog-backend-module-ai-model/package.json b/plugins/catalog-backend-module-ai-model/package.json index c1cc2dbee5..ca6159fba6 100644 --- a/plugins/catalog-backend-module-ai-model/package.json +++ b/plugins/catalog-backend-module-ai-model/package.json @@ -1,7 +1,7 @@ { "name": "@backstage/plugin-catalog-backend-module-ai-model", "version": "0.1.0", - "description": "Adds support for the AIResource entity kind to the catalog backend plugin.", + "description": "Adds support for the AiResource entity kind to the catalog backend plugin.", "backstage": { "role": "backend-plugin-module", "pluginId": "catalog", @@ -18,16 +18,12 @@ "license": "Apache-2.0", "exports": { ".": "./src/index.ts", - "./alpha": "./src/alpha.ts", "./package.json": "./package.json" }, "main": "src/index.ts", "types": "src/index.ts", "typesVersions": { "*": { - "alpha": [ - "src/alpha.ts" - ], "package.json": [ "package.json" ] @@ -48,8 +44,7 @@ "dependencies": { "@backstage/backend-plugin-api": "workspace:^", "@backstage/catalog-model": "workspace:^", - "@backstage/plugin-catalog-node": "workspace:^", - "@backstage/types": "workspace:^" + "@backstage/plugin-catalog-node": "workspace:^" }, "devDependencies": { "@backstage/backend-test-utils": "workspace:^", diff --git a/plugins/catalog-backend-module-ai-model/report-alpha.api.md b/plugins/catalog-backend-module-ai-model/report-alpha.api.md deleted file mode 100644 index 0da8b27915..0000000000 --- a/plugins/catalog-backend-module-ai-model/report-alpha.api.md +++ /dev/null @@ -1,12 +0,0 @@ -## API Report File for "@backstage/plugin-catalog-backend-module-ai-model" - -> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). - -```ts -import { CatalogModelLayer } from '@backstage/catalog-model/alpha'; - -// @alpha -export const aiResourceEntityModel: CatalogModelLayer; - -// (No @packageDocumentation comment for this package) -``` diff --git a/plugins/catalog-backend-module-ai-model/report.api.md b/plugins/catalog-backend-module-ai-model/report.api.md index 1e5315d601..b1249ee146 100644 --- a/plugins/catalog-backend-module-ai-model/report.api.md +++ b/plugins/catalog-backend-module-ai-model/report.api.md @@ -4,65 +4,8 @@ ```ts import { BackendFeature } from '@backstage/backend-plugin-api'; -import { Entity } from '@backstage/catalog-model'; -import { KindValidator } from '@backstage/catalog-model'; - -// @public -export type AiResourceEntityV1alpha1 = - | AiResourceEntityV1alpha1Default - | SkillAiResourceEntityV1alpha1; - -// @public -export interface AiResourceEntityV1alpha1Default extends Entity { - // (undocumented) - apiVersion: 'backstage.io/v1alpha1'; - // (undocumented) - kind: 'AiResource'; - // (undocumented) - spec: { - type: string; - lifecycle: string; - owner: string; - system?: string; - }; -} - -// @public -export const aiResourceEntityV1alpha1Validator: KindValidator; // @public const catalogModuleAiResourceEntityModel: BackendFeature; export default catalogModuleAiResourceEntityModel; - -// @public -export const isAiResourceEntity: ( - entity: Entity, -) => entity is AiResourceEntityV1alpha1; - -// @public -export const isSkillAiResourceEntity: ( - entity: Entity, -) => entity is SkillAiResourceEntityV1alpha1; - -// @public -export interface SkillAiResourceEntityV1alpha1 extends Entity { - // (undocumented) - apiVersion: 'backstage.io/v1alpha1'; - // (undocumented) - kind: 'AiResource'; - // (undocumented) - spec: { - type: 'skill'; - lifecycle: string; - owner: string; - system?: string; - disciplines?: string[]; - categories?: string[]; - agents?: string[]; - dependsOn?: string[]; - }; -} - -// @public -export const skillAiResourceEntityV1alpha1Validator: KindValidator; ``` diff --git a/plugins/catalog-backend-module-ai-model/src/alpha.ts b/plugins/catalog-backend-module-ai-model/src/alpha.ts deleted file mode 100644 index 6f9fc0eb7b..0000000000 --- a/plugins/catalog-backend-module-ai-model/src/alpha.ts +++ /dev/null @@ -1,17 +0,0 @@ -/* - * Copyright 2026 The Backstage Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -export { aiResourceEntityModel } from './AiResourceEntityV1alpha1'; diff --git a/plugins/catalog-backend-module-ai-model/src/index.ts b/plugins/catalog-backend-module-ai-model/src/index.ts index 7b6a6cba36..fedbd274eb 100644 --- a/plugins/catalog-backend-module-ai-model/src/index.ts +++ b/plugins/catalog-backend-module-ai-model/src/index.ts @@ -20,15 +20,4 @@ * @packageDocumentation */ -export type { - AiResourceEntityV1alpha1, - AiResourceEntityV1alpha1Default, - SkillAiResourceEntityV1alpha1, -} from './AiResourceEntityV1alpha1'; -export { - aiResourceEntityV1alpha1Validator, - skillAiResourceEntityV1alpha1Validator, - isAiResourceEntity, - isSkillAiResourceEntity, -} from './AiResourceEntityV1alpha1'; export { catalogModuleAiResourceEntityModel as default } from './module'; diff --git a/plugins/catalog-backend-module-ai-model/src/module.ts b/plugins/catalog-backend-module-ai-model/src/module.ts index fc293889b4..f2807a1cab 100644 --- a/plugins/catalog-backend-module-ai-model/src/module.ts +++ b/plugins/catalog-backend-module-ai-model/src/module.ts @@ -15,9 +15,11 @@ */ import { createBackendModule } from '@backstage/backend-plugin-api'; -import { CatalogModelSources } from '@backstage/catalog-model/alpha'; +import { + CatalogModelSources, + aiResourceEntityModel, +} from '@backstage/catalog-model/alpha'; import { catalogModelExtensionPoint } from '@backstage/plugin-catalog-node/alpha'; -import { aiResourceEntityModel } from './AiResourceEntityV1alpha1'; /** * Registers support for the AiResource entity kind in the catalog. diff --git a/yarn.lock b/yarn.lock index 3ed08d279b..6655516238 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4768,7 +4768,6 @@ __metadata: "@backstage/catalog-model": "workspace:^" "@backstage/cli": "workspace:^" "@backstage/plugin-catalog-node": "workspace:^" - "@backstage/types": "workspace:^" languageName: unknown linkType: soft