@red-hat-developer-hub/backstage-plugin-ai-skills-common 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -305,18 +305,22 @@ declare function computeCatalogName(tuple: IdentityTuple): string;
 interface NormalizeTagsResult {
     /** Valid, deduplicated tags in lowercase. */
     tags: string[];
-    /** Diagnostic messages for tags that were dropped. */
+    /**
+     * Diagnostic messages for tags that were dropped.
+     *
+     * @remarks
+     * Message text is informational and may change. Consumers must not
+     * treat wording as a stable API or use it for programmatic decisions.
+     */
     diagnostics: string[];
 }
 /**
  * Normalizes tags for catalog use per design D3/D5.
  *
  * Trims whitespace, lowercases, deduplicates, and retains only values
- * accepted by an extended catalog tag pattern (per design D3/D5) that
- * allows colons, plus signs, and hash characters beyond the standard
- * Backstage tag validator. Invalid or overlength values are omitted
- * with a diagnostic — tags are never truncated and replacement
- * characters are never synthesized.
+ * accepted by {@link CATALOG_TAG_PATTERN} (per design D3/D5). Invalid or
+ * overlength values are omitted with a diagnostic — tags are never
+ * truncated and replacement characters are never synthesized.
  *
  * @public
  */
@@ -545,6 +549,309 @@ declare const SKILLS_ENDPOINT_BASE = "/skills";
  */
 declare const MAX_RESPONSE_BYTES: number;
 
+
+
+
+
+/**
+ * Parsed OCI SkillCard metadata fields.
+ *
+ * Fields use `unknown` because the YAML parser may produce any type.
+ * The normalizer validates and selects correctly typed values.
+ *
+ * @remarks
+ * The `unknown` field types are deliberate and stable for the v1 contract.
+ * Native metadata arrives as parsed YAML/JSON and may contain any type.
+ * Narrowing to concrete types in a future minor release would be a
+ * breaking TypeScript change; any such narrowing will be reserved for v2.
+ *
+ * @public
+ */
+interface OciSkillCardMetadata {
+    /** Display name (`metadata.display-name`). */
+    'display-name'?: unknown;
+    /** Name (`metadata.name`). */
+    name?: unknown;
+    /** Description (`metadata.description`). */
+    description?: unknown;
+    /** Declared version (`metadata.version`). */
+    version?: unknown;
+    /** License identifier (`metadata.license`). */
+    license?: unknown;
+    /** Author list (`metadata.authors`). */
+    authors?: unknown;
+    /** Metadata tags (`metadata.tags`). */
+    tags?: unknown;
+    /** Compatibility info (`metadata.compatibility`). */
+    compatibility?: unknown;
+    /** Namespace scope (`metadata.namespace`). */
+    namespace?: unknown;
+}
+/**
+ * Parsed OCI SkillCard spec fields.
+ *
+ * @public
+ */
+interface OciSkillCardSpec {
+    /** System prompt (`spec.prompt`). */
+    prompt?: unknown;
+}
+/**
+ * Parsed OCI SkillCard document.
+ *
+ * @public
+ */
+interface OciSkillCard {
+    /** SkillCard metadata section. */
+    metadata?: OciSkillCardMetadata;
+    /** SkillCard spec section. */
+    spec?: OciSkillCardSpec;
+}
+/**
+ * Shared base interface for parsed Markdown frontmatter.
+ *
+ * Both OCI and npx skill documents use the same YAML frontmatter
+ * structure. This base captures the common shape. Dedicated aliases
+ * ({@link OciMarkdownFrontmatter}, {@link NpxFrontmatter}) represent
+ * semantically distinct domains and may diverge independently in
+ * future versions.
+ *
+ * @remarks
+ * The `unknown` field types are deliberate and stable for the v1 contract.
+ * See {@link OciSkillCardMetadata} for the rationale.
+ *
+ * @public
+ */
+interface MarkdownFrontmatter {
+    /** Top-level name. */
+    name?: unknown;
+    /** Top-level description. */
+    description?: unknown;
+    /** Top-level version (frontmatter `version`). */
+    version?: unknown;
+    /** Top-level license. */
+    license?: unknown;
+    /** Top-level compatibility. */
+    compatibility?: unknown;
+    /** Nested metadata block in frontmatter. */
+    metadata?: FrontmatterMetadata;
+}
+/**
+ * Nested metadata block within parsed Markdown frontmatter.
+ *
+ * @remarks
+ * The `unknown` field types are deliberate and stable for the v1 contract.
+ * See {@link OciSkillCardMetadata} for the rationale.
+ *
+ * @public
+ */
+interface FrontmatterMetadata {
+    /** Frontmatter `metadata.version`. */
+    version?: unknown;
+    /** Frontmatter `metadata.author` (string or object). */
+    author?: unknown;
+    /** Frontmatter `metadata.tags`. */
+    tags?: unknown;
+    /** Frontmatter `metadata.owner`. */
+    owner?: unknown;
+    /** Frontmatter `metadata.lifecycle`. */
+    lifecycle?: unknown;
+}
+/**
+ * Parsed Markdown frontmatter from an OCI skill document
+ * (SKILL.md or SKILLS.md).
+ *
+ * Structurally identical to {@link MarkdownFrontmatter} but kept as a
+ * separate named type so the OCI and npx domains can diverge
+ * independently in future versions without a breaking rename.
+ *
+ * @public
+ */
+type OciMarkdownFrontmatter = MarkdownFrontmatter;
+/**
+ * Combined parsed OCI native input for normalization.
+ *
+ * @public
+ */
+interface OciNativeInput {
+    /** Parsed SkillCard document. */
+    skillCard?: OciSkillCard;
+    /** Parsed Markdown frontmatter. */
+    frontmatter?: OciMarkdownFrontmatter;
+}
+/**
+ * Parsed npx discovery entry from an Agent Skills index.
+ *
+ * @remarks
+ * The `unknown` field types are deliberate and stable for the v1 contract.
+ * See {@link OciSkillCardMetadata} for the rationale.
+ *
+ * @public
+ */
+interface NpxDiscoveryEntry {
+    /** Discovery entry name. */
+    name?: unknown;
+    /** Discovery entry description. */
+    description?: unknown;
+    /**
+     * Artifact format type.
+     *
+     * @remarks
+     * Currently only `'skill-md'` is accepted by the normalizer. Any other
+     * non-nullish value is omitted from the normalized record with a
+     * diagnostic. The field is typed `unknown` because the discovery index
+     * may contain arbitrary strings; the normalizer validates at runtime.
+     */
+    type?: unknown;
+}
+/**
+ * Parsed Markdown frontmatter from an npx skill document.
+ *
+ * Structurally identical to {@link MarkdownFrontmatter} but kept as a
+ * separate named type so the npx and OCI domains can diverge
+ * independently in future versions without a breaking rename.
+ *
+ * @public
+ */
+type NpxFrontmatter = MarkdownFrontmatter;
+/**
+ * Combined parsed npx native input for normalization.
+ *
+ * @public
+ */
+interface NpxNativeInput {
+    /** Parsed discovery entry. */
+    entry?: NpxDiscoveryEntry;
+    /** Parsed Markdown frontmatter. */
+    frontmatter?: NpxFrontmatter;
+}
+/**
+ * Trusted source identity and integrity fields provided by the
+ * connector after verified acquisition. These are never derived
+ * from native metadata or user-supplied frontmatter.
+ *
+ * @public
+ */
+interface TrustedSourceInput {
+    /** Stable identity key within this source. */
+    key: string;
+    /** Digest-addressed OCI URI or fragment-free HTTPS URL. */
+    sourceUri: string;
+    /** Content digest in `sha256:<64 lowercase hex digits>` format. */
+    digest: string;
+}
+/**
+ * A single diagnostic produced during metadata normalization.
+ *
+ * @public
+ */
+interface NormalizationDiagnostic {
+    /** The normalized field that triggered the diagnostic. */
+    field: string;
+    /**
+     * Human-readable description of the issue.
+     *
+     * @remarks
+     * The `message` field is informational and not part of the stable API
+     * contract. Diagnostic wording may change between minor releases.
+     * Downstream consumers should not assert on exact message text.
+     */
+    message: string;
+}
+/**
+ * Result of a metadata normalization operation.
+ *
+ * When `record` is non-null, the normalization succeeded and the record
+ * is schema-valid. Diagnostics may still be present for omitted optional
+ * fields. When `record` is null, the normalization failed due to missing
+ * required fields or other fatal issues.
+ *
+ * @public
+ */
+interface NormalizationResult<T> {
+    /** The normalized record, or null if normalization failed. */
+    record: T | null;
+    /** Diagnostics produced during normalization. */
+    diagnostics: NormalizationDiagnostic[];
+}
+/**
+ * Normalizes OCI metadata into an `OciSkillRecord` using design D3
+ * precedence rules.
+ *
+ * Accepts parsed, verified OCI SkillCard metadata and Markdown
+ * frontmatter plus trusted source identity/integrity fields from
+ * the connector. Returns a schema-valid record or null with
+ * diagnostics.
+ *
+ * D3 OCI precedence order per field:
+ * - name: `metadata.display-name`, `metadata.name`, frontmatter `name`
+ * - description: `metadata.description`, frontmatter `description`
+ * - version: `metadata.version`, frontmatter `metadata.version`,
+ *   frontmatter `version`
+ * - license: `metadata.license`, frontmatter `license`
+ * - authors: `metadata.authors`, frontmatter `metadata.author`
+ * - tags: `metadata.tags`, frontmatter `metadata.tags`
+ * - compatibility: `metadata.compatibility`, frontmatter `compatibility`
+ * - owner: frontmatter `metadata.owner`
+ * - lifecycle: frontmatter `metadata.lifecycle`
+ * - extensions.oci.namespace: `metadata.namespace`
+ * - extensions.oci.prompt: `spec.prompt`
+ *
+ * @public
+ */
+declare function normalizeOciMetadata(native: OciNativeInput, trusted: TrustedSourceInput): NormalizationResult<OciSkillRecord>;
+/**
+ * Normalizes npx metadata into an `NpxSkillRecord` using design D3
+ * precedence rules.
+ *
+ * Accepts parsed, verified npx discovery entry and Markdown frontmatter
+ * plus trusted source identity/integrity fields from the connector.
+ * Returns a schema-valid record or null with diagnostics.
+ *
+ * D3 npx precedence order per field:
+ * - name: frontmatter `name`, discovery entry `name`
+ * - description: frontmatter `description`, discovery entry `description`
+ * - version: frontmatter `metadata.version`, frontmatter `version`
+ * - license: frontmatter `license`
+ * - authors: frontmatter `metadata.author`
+ * - tags: frontmatter `metadata.tags`
+ * - compatibility: frontmatter `compatibility`
+ * - owner: frontmatter `metadata.owner`
+ * - lifecycle: frontmatter `metadata.lifecycle`
+ * - extensions.npx.type: discovery entry `type`
+ *
+ * @public
+ */
+declare function normalizeNpxMetadata(native: NpxNativeInput, trusted: TrustedSourceInput): NormalizationResult<NpxSkillRecord>;
+
+/**
+ * Shared catalog tag validation constants used by both the D3
+ * metadata normalizers and the D5 catalog helpers.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Catalog tag validation pattern.
+ *
+ * Tags contain lowercase alphanumeric characters, colons, plus signs,
+ * and hash characters, separated by single hyphens.
+ *
+ * @remarks
+ * This pattern matches Backstage's default catalog tag validator.
+ * Tests compare it and the length limit with `makeValidator().isValidTag`
+ * from `@backstage/catalog-model`, a development-only dependency.
+ * Runtime consumers do not need a Backstage dependency for validation.
+ *
+ * @public
+ */
+declare const CATALOG_TAG_PATTERN: RegExp;
+/**
+ * Maximum tag length accepted by the Backstage catalog.
+ *
+ * @public
+ */
+declare const MAX_TAG_LENGTH = 63;
+
 /**
  * Reusable OCI and npx contract fixtures for connector and provider tests.
  *
@@ -557,6 +864,19 @@ declare const MAX_RESPONSE_BYTES: number;
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 /**
  * OCI source fixture for contract tests.
@@ -732,6 +1052,122 @@ declare const invalidFailedWithSkills: unknown;
  * @public
  */
 declare const invalidSnapshotNonUtcTimestamp: unknown;
+/**
+ * OCI SkillCard with full metadata including namespace and prompt.
+ *
+ * @public
+ */
+declare const ociSkillCardFull: OciSkillCard;
+/**
+ * OCI Markdown frontmatter with full metadata.
+ *
+ * The `metadata.version` here intentionally conflicts with the SkillCard
+ * version to verify D3 precedence: SkillCard `metadata.version` (1.0.0)
+ * wins over frontmatter `metadata.version` (1.0).
+ *
+ * @public
+ */
+declare const ociMarkdownFrontmatterFull: OciMarkdownFrontmatter;
+/**
+ * OCI SkillCard with conflicting version.
+ *
+ * SkillCard `metadata.version` is 1.0.0 while the paired frontmatter
+ * declares `metadata.version: "1.0"` and `version: "0.9.0"`. D3
+ * precedence selects 1.0.0 as the declared version.
+ *
+ * @public
+ */
+declare const ociSkillCardConflictingVersion: OciSkillCard;
+/**
+ * OCI Markdown frontmatter with conflicting version values.
+ *
+ * Paired with {@link ociSkillCardConflictingVersion} to test D3
+ * version precedence. The SkillCard version (1.0.0) wins.
+ *
+ * @public
+ */
+declare const ociMarkdownFrontmatterConflictingVersion: OciMarkdownFrontmatter;
+/**
+ * OCI SkillCard with only a name — no optional metadata.
+ *
+ * @public
+ */
+declare const ociSkillCardMinimal: OciSkillCard;
+/**
+ * Combined OCI native input with full metadata.
+ *
+ * @public
+ */
+declare const ociNativeInputFull: OciNativeInput;
+/**
+ * Combined OCI native input with conflicting versions.
+ *
+ * @public
+ */
+declare const ociNativeInputConflictingVersion: OciNativeInput;
+/**
+ * Combined OCI native input with only a minimal SkillCard.
+ *
+ * @public
+ */
+declare const ociNativeInputMinimal: OciNativeInput;
+/**
+ * Trusted source input for OCI fixtures.
+ *
+ * @public
+ */
+declare const ociTrustedInput: TrustedSourceInput;
+/**
+ * npx discovery entry with full metadata.
+ *
+ * @public
+ */
+declare const npxDiscoveryEntryFull: NpxDiscoveryEntry;
+/**
+ * npx Markdown frontmatter with full metadata.
+ *
+ * @public
+ */
+declare const npxFrontmatterFull: NpxFrontmatter;
+/**
+ * npx discovery entry with only a name (minimal).
+ *
+ * @public
+ */
+declare const npxDiscoveryEntryMinimal: NpxDiscoveryEntry;
+/**
+ * npx Markdown frontmatter with conflicting version values.
+ *
+ * `metadata.version` (2.0.0) has higher precedence than top-level
+ * `version` (1.5.0) per D3.
+ *
+ * @public
+ */
+declare const npxFrontmatterConflictingVersion: NpxFrontmatter;
+/**
+ * Combined npx native input with full metadata.
+ *
+ * @public
+ */
+declare const npxNativeInputFull: NpxNativeInput;
+/**
+ * Combined npx native input with conflicting versions.
+ *
+ * @public
+ */
+declare const npxNativeInputConflictingVersion: NpxNativeInput;
+/**
+ * Combined npx native input with minimal data.
+ *
+ * @public
+ */
+declare const npxNativeInputMinimal: NpxNativeInput;
+/**
+ * Trusted source input for npx fixtures.
+ *
+ * @public
+ */
+declare const npxTrustedInput: TrustedSourceInput;
 
 /**
  * Shared v1 skill record and snapshot contract for skill connectors
@@ -760,5 +1196,18 @@ declare const invalidSnapshotNonUtcTimestamp: unknown;
 
 
 
-export { MAX_RESPONSE_BYTES, MAX_SNAPSHOT_BYTES, MAX_SNAPSHOT_RECORDS, SKILLS_ENDPOINT_BASE, SUPPORTED_SCHEMA_VERSION, boundSnapshot, buildNpxRef, buildOciRef, computeCatalogName, createFailedSnapshot, createLoadingSnapshot, invalidFailedWithSkills, invalidLoadingWithObservedAt, invalidLoadingWithSkills, invalidNpxRecordWithOciExtension, invalidOciRecordUnknownExtKey, invalidOciRecordWithNpxExtension, invalidRecordBadDigest, invalidRecordEmptyKey, invalidRecordShortDigest, invalidSnapshotBadVersion, invalidSnapshotDuplicateKeys, invalidSnapshotNonUtcTimestamp, invalidSnapshotOverlappingKeys, invalidSnapshotReadyWithFailedKeys, isNpxSkillRecord, isOciSkillRecord, isValidDigest, isValidUtcTimestamp, normalizeTags, npxSource, ociSource, parseNpxRef, parseOciRef, resolveVersion, sortRecordsByKey, validFailedSnapshot, validLoadingSnapshot, validNpxRecordFull, validNpxRecordMinimal, validNpxRecordWithQuery, validNpxSnapshotReady, validOciRecordEmptyExtensions, validOciRecordFull, validOciRecordMinimal, validOciSnapshotReady, validPartialEmptySnapshot, validPartialSnapshot, validReadyEmptySnapshot, validateSnapshot, validateSnapshotSize };
-export type { BoundSnapshotOptions, IdentityTuple, NormalizeTagsResult, NpxExtensions, NpxRef, NpxSkillRecord, OciExtensions, OciRef, OciSkillRecord, SkillAuthor, SkillRecord, SkillSnapshot, SkillSnapshotV1, SkillSourceType, SnapshotSource, SnapshotStatus, ValidationResult };
+
+
+
+
+
+
+
+
+
+
+
+
+
+export { CATALOG_TAG_PATTERN, MAX_RESPONSE_BYTES, MAX_SNAPSHOT_BYTES, MAX_SNAPSHOT_RECORDS, MAX_TAG_LENGTH, SKILLS_ENDPOINT_BASE, SUPPORTED_SCHEMA_VERSION, boundSnapshot, buildNpxRef, buildOciRef, computeCatalogName, createFailedSnapshot, createLoadingSnapshot, invalidFailedWithSkills, invalidLoadingWithObservedAt, invalidLoadingWithSkills, invalidNpxRecordWithOciExtension, invalidOciRecordUnknownExtKey, invalidOciRecordWithNpxExtension, invalidRecordBadDigest, invalidRecordEmptyKey, invalidRecordShortDigest, invalidSnapshotBadVersion, invalidSnapshotDuplicateKeys, invalidSnapshotNonUtcTimestamp, invalidSnapshotOverlappingKeys, invalidSnapshotReadyWithFailedKeys, isNpxSkillRecord, isOciSkillRecord, isValidDigest, isValidUtcTimestamp, normalizeNpxMetadata, normalizeOciMetadata, normalizeTags, npxDiscoveryEntryFull, npxDiscoveryEntryMinimal, npxFrontmatterConflictingVersion, npxFrontmatterFull, npxNativeInputConflictingVersion, npxNativeInputFull, npxNativeInputMinimal, npxSource, npxTrustedInput, ociMarkdownFrontmatterConflictingVersion, ociMarkdownFrontmatterFull, ociNativeInputConflictingVersion, ociNativeInputFull, ociNativeInputMinimal, ociSkillCardConflictingVersion, ociSkillCardFull, ociSkillCardMinimal, ociSource, ociTrustedInput, parseNpxRef, parseOciRef, resolveVersion, sortRecordsByKey, validFailedSnapshot, validLoadingSnapshot, validNpxRecordFull, validNpxRecordMinimal, validNpxRecordWithQuery, validNpxSnapshotReady, validOciRecordEmptyExtensions, validOciRecordFull, validOciRecordMinimal, validOciSnapshotReady, validPartialEmptySnapshot, validPartialSnapshot, validReadyEmptySnapshot, validateSnapshot, validateSnapshotSize };
+export type { BoundSnapshotOptions, FrontmatterMetadata, IdentityTuple, MarkdownFrontmatter, NormalizationDiagnostic, NormalizationResult, NormalizeTagsResult, NpxDiscoveryEntry, NpxExtensions, NpxFrontmatter, NpxNativeInput, NpxRef, NpxSkillRecord, OciExtensions, OciMarkdownFrontmatter, OciNativeInput, OciRef, OciSkillCard, OciSkillCardMetadata, OciSkillCardSpec, OciSkillRecord, SkillAuthor, SkillRecord, SkillSnapshot, SkillSnapshotV1, SkillSourceType, SnapshotSource, SnapshotStatus, TrustedSourceInput, ValidationResult };

package/dist/index.esm.js

@@ -2,5 +2,7 @@ export { MAX_SNAPSHOT_BYTES, MAX_SNAPSHOT_RECORDS, SUPPORTED_SCHEMA_VERSION, isN
 export { buildNpxRef, buildOciRef, computeCatalogName, normalizeTags, parseNpxRef, parseOciRef, resolveVersion } from './catalog-helpers.esm.js';
 export { boundSnapshot, createFailedSnapshot, createLoadingSnapshot, sortRecordsByKey } from './snapshot.esm.js';
 export { MAX_RESPONSE_BYTES, SKILLS_ENDPOINT_BASE } from './rest-contract.esm.js';
-export { invalidFailedWithSkills, invalidLoadingWithObservedAt, invalidLoadingWithSkills, invalidNpxRecordWithOciExtension, invalidOciRecordUnknownExtKey, invalidOciRecordWithNpxExtension, invalidRecordBadDigest, invalidRecordEmptyKey, invalidRecordShortDigest, invalidSnapshotBadVersion, invalidSnapshotDuplicateKeys, invalidSnapshotNonUtcTimestamp, invalidSnapshotOverlappingKeys, invalidSnapshotReadyWithFailedKeys, npxSource, ociSource, validFailedSnapshot, validLoadingSnapshot, validNpxRecordFull, validNpxRecordMinimal, validNpxRecordWithQuery, validNpxSnapshotReady, validOciRecordEmptyExtensions, validOciRecordFull, validOciRecordMinimal, validOciSnapshotReady, validPartialEmptySnapshot, validPartialSnapshot, validReadyEmptySnapshot } from './fixtures.esm.js';
+export { normalizeNpxMetadata, normalizeOciMetadata } from './normalizer.esm.js';
+export { CATALOG_TAG_PATTERN, MAX_TAG_LENGTH } from './tag-constants.esm.js';
+export { invalidFailedWithSkills, invalidLoadingWithObservedAt, invalidLoadingWithSkills, invalidNpxRecordWithOciExtension, invalidOciRecordUnknownExtKey, invalidOciRecordWithNpxExtension, invalidRecordBadDigest, invalidRecordEmptyKey, invalidRecordShortDigest, invalidSnapshotBadVersion, invalidSnapshotDuplicateKeys, invalidSnapshotNonUtcTimestamp, invalidSnapshotOverlappingKeys, invalidSnapshotReadyWithFailedKeys, npxDiscoveryEntryFull, npxDiscoveryEntryMinimal, npxFrontmatterConflictingVersion, npxFrontmatterFull, npxNativeInputConflictingVersion, npxNativeInputFull, npxNativeInputMinimal, npxSource, npxTrustedInput, ociMarkdownFrontmatterConflictingVersion, ociMarkdownFrontmatterFull, ociNativeInputConflictingVersion, ociNativeInputFull, ociNativeInputMinimal, ociSkillCardConflictingVersion, ociSkillCardFull, ociSkillCardMinimal, ociSource, ociTrustedInput, validFailedSnapshot, validLoadingSnapshot, validNpxRecordFull, validNpxRecordMinimal, validNpxRecordWithQuery, validNpxSnapshotReady, validOciRecordEmptyExtensions, validOciRecordFull, validOciRecordMinimal, validOciSnapshotReady, validPartialEmptySnapshot, validPartialSnapshot, validReadyEmptySnapshot } from './fixtures.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":";;;;;;"}