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

package/dist/index.d.ts

@@ -0,0 +1,764 @@
+/**
+ * Supported source types for skill connectors.
+ *
+ * This is a closed union. Adding a new member is a breaking change
+ * for consumers performing exhaustive switching.
+ *
+ * @public
+ */
+type SkillSourceType = 'oci' | 'npx';
+/**
+ * Supported snapshot statuses per design D6.
+ *
+ * - `loading` — first acquisition is in progress
+ * - `ready` — all discovery pages and candidates completed without failures
+ * - `partial` — discovery or processing was incomplete
+ * - `failed` — no usable discovery result could be obtained
+ *
+ * This is a closed union. Adding a new member is a breaking change
+ * for consumers performing exhaustive switching.
+ *
+ * @public
+ */
+type SnapshotStatus = 'loading' | 'ready' | 'partial' | 'failed';
+/**
+ * An author entry with a required name and optional email.
+ *
+ * @public
+ */
+interface SkillAuthor {
+    /** Display name of the author. */
+    name: string;
+    /** Optional contact email. */
+    email?: string;
+}
+/**
+ * A normalized v1 skill record per design D2.
+ *
+ * `key`, `name`, `sourceUri`, and `digest` are non-empty required fields.
+ * Optional fields are omitted when absent.
+ *
+ * @public
+ */
+interface SkillRecord {
+    /** Stable identity within this source; never a content digest. */
+    key: string;
+    /** Published human-readable name. */
+    name: string;
+    /** Optional description. */
+    description?: string;
+    /** Declared version, before catalog SemVer fallback. */
+    version?: string;
+    /** SPDX license identifier or free-text license. */
+    license?: string;
+    /** Skill authors — informational only, never implies catalog ownership. */
+    authors?: SkillAuthor[];
+    /** Metadata tags. */
+    tags?: string[];
+    /** Compatibility information. */
+    compatibility?: string;
+    /** Optional catalog owner hint. */
+    owner?: string;
+    /** Optional catalog lifecycle hint. */
+    lifecycle?: string;
+    /**
+     * Digest-addressed OCI URI or fragment-free HTTPS URL.
+     * OCI: `oci://<registry>/<repository>@sha256:<hex>`
+     * npx: absolute HTTPS artifact URL.
+     */
+    sourceUri: string;
+    /** Content digest in `sha256:<64 lowercase hex digits>` format. */
+    digest: string;
+}
+/**
+ * OCI-specific extension fields.
+ *
+ * @public
+ */
+interface OciExtensions {
+    /** OCI namespace scope for the skill image. */
+    namespace?: string;
+    /** System prompt embedded in the skill image metadata. */
+    prompt?: string;
+}
+/**
+ * npx-specific extension fields.
+ *
+ * @public
+ */
+interface NpxExtensions {
+    /**
+     * Artifact format type. Currently only `'skill-md'` is supported.
+     * This is a closed literal — adding a new format requires expanding
+     * both the type and the validator, which are breaking changes.
+     */
+    type?: 'skill-md';
+}
+/**
+ * A skill record from an OCI source with optional OCI-specific extensions.
+ *
+ * @public
+ */
+interface OciSkillRecord extends SkillRecord {
+    /** OCI-specific extension fields scoped under the `oci` container. */
+    extensions?: {
+        oci?: OciExtensions;
+    };
+}
+/**
+ * A skill record from an npx source with optional npx-specific extensions.
+ *
+ * @public
+ */
+interface NpxSkillRecord extends SkillRecord {
+    /** npx-specific extension fields scoped under the `npx` container. */
+    extensions?: {
+        npx?: NpxExtensions;
+    };
+}
+/**
+ * Source identity within a snapshot.
+ *
+ * @public
+ */
+interface SnapshotSource {
+    /** Configured source ID. */
+    id: string;
+    /** Source type discriminator. */
+    type: SkillSourceType;
+}
+/**
+ * A versioned v1 skill snapshot per design D2.
+ *
+ * One response contains one bounded snapshot: at most 1,000 records and
+ * 5 MiB of serialized JSON.
+ *
+ * @public
+ */
+interface SkillSnapshot {
+    /** Schema version; must be `'1'` for v1. */
+    schemaVersion: '1';
+    /** Source identity. */
+    source: SnapshotSource;
+    /** Snapshot completeness status per design D6. */
+    status: SnapshotStatus;
+    /**
+     * UTC completion time as ISO 8601 string, or `null` before first attempt.
+     * `loading` snapshots have `null`; completed attempts have a UTC time.
+     */
+    observedAt: string | null;
+    /** Successfully normalized skill records. */
+    skills: Array<OciSkillRecord | NpxSkillRecord>;
+    /** Stable keys of skills that failed processing; disjoint from skill keys. */
+    failedSkillKeys: string[];
+}
+/**
+ * Forward-compatibility alias for the v1 snapshot interface.
+ *
+ * When v2 is introduced, `SkillSnapshot` will widen to a union and
+ * `SkillSnapshotV1` will continue to refer to the v1 shape, allowing
+ * consumers to migrate without a breaking change.
+ *
+ * @public
+ */
+type SkillSnapshotV1 = SkillSnapshot;
+
+
+
+
+
+
+
+
+
+
+
+/**
+ * Maximum number of records in a single snapshot (design D2).
+ *
+ * @public
+ */
+declare const MAX_SNAPSHOT_RECORDS = 1000;
+/**
+ * Maximum serialized snapshot size in bytes (design D2: 5 MiB).
+ *
+ * @public
+ */
+declare const MAX_SNAPSHOT_BYTES: number;
+/**
+ * Supported schema version.
+ *
+ * @public
+ */
+declare const SUPPORTED_SCHEMA_VERSION = "1";
+/**
+ * Result of a validation operation.
+ *
+ * @public
+ */
+interface ValidationResult {
+    /** Whether the validated input passed all checks. */
+    valid: boolean;
+    /** Human-readable error messages for each failed check. */
+    errors: string[];
+}
+/**
+ * Validates a SHA-256 digest string.
+ *
+ * @public
+ */
+declare function isValidDigest(digest: string): boolean;
+/**
+ * Validates an ISO 8601 UTC date string. Accepts strings ending in `Z`
+ * or `+00:00` that parse to a valid Date.
+ *
+ * @public
+ */
+declare function isValidUtcTimestamp(value: string): boolean;
+/**
+ * Validates a complete v1 SkillSnapshot.
+ *
+ * Checks:
+ * - Schema version is supported
+ * - Source identity is valid
+ * - Status is valid
+ * - Status invariants (loading/ready/partial/failed) per design D6
+ * - Timestamp validity
+ * - Record validation including source-discriminated extensions
+ * - Unique record keys
+ * - Disjoint successful/failed key sets
+ * - Count and size bounds
+ *
+ * Does NOT check deterministic ordering — that is the producer's
+ * responsibility enforced by {@link boundSnapshot}.
+ *
+ * @public
+ */
+declare function validateSnapshot(snapshot: unknown): ValidationResult;
+/**
+ * Validates the serialized byte size of a snapshot against the 5 MiB
+ * limit. Call after `validateSnapshot` succeeds.
+ *
+ * @public
+ */
+declare function validateSnapshotSize(snapshot: SkillSnapshot): ValidationResult;
+/**
+ * Type guard for OciSkillRecord.
+ *
+ * Requires the snapshot's `source.type` to disambiguate records that
+ * have no `extensions` field — a bare record is only an OCI record
+ * when the enclosing snapshot source is `'oci'`.
+ *
+ * @public
+ */
+declare function isOciSkillRecord(record: SkillRecord, sourceType: SkillSourceType): record is OciSkillRecord;
+/**
+ * Type guard for NpxSkillRecord.
+ *
+ * Requires the snapshot's `source.type` to disambiguate records that
+ * have no `extensions` field — a bare record is only an npx record
+ * when the enclosing snapshot source is `'npx'`.
+ *
+ * @public
+ */
+declare function isNpxSkillRecord(record: SkillRecord, sourceType: SkillSourceType): record is NpxSkillRecord;
+
+
+
+/**
+ * The identity tuple used for deterministic catalog entity naming.
+ *
+ * @public
+ */
+interface IdentityTuple {
+    /** Source type discriminator. */
+    type: SkillSourceType;
+    /** Configured source ID. */
+    id: string;
+    /** Stable record key within the source. */
+    key: string;
+}
+/**
+ * Computes the deterministic catalog entity name from an identity tuple.
+ *
+ * Per design D5, the name is `skill-` followed by the first 56 lowercase
+ * hex digits of the SHA-256 hash of the compact JSON UTF-8 encoding of
+ * `[source.type, source.id, record.key]`.
+ *
+ * Names, versions, tags, and content digests do not affect entity
+ * identity. A source ID or native key change creates a different name.
+ *
+ * @remarks
+ * The hashing algorithm (SHA-256 of compact JSON identity tuple, truncated
+ * to 56 hex digits) is part of the stable public contract. Persisted
+ * entities depend on this producing the same output for the same input.
+ * Any change to the algorithm constitutes a breaking (major) change.
+ *
+ * @public
+ */
+declare function computeCatalogName(tuple: IdentityTuple): string;
+/**
+ * Result of tag normalization.
+ *
+ * @public
+ */
+interface NormalizeTagsResult {
+    /** Valid, deduplicated tags in lowercase. */
+    tags: string[];
+    /** Diagnostic messages for tags that were dropped. */
+    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.
+ *
+ * @public
+ */
+declare function normalizeTags(tags: string[]): NormalizeTagsResult;
+/**
+ * Resolves a catalog version from a declared version string and record
+ * digest, per design D5.
+ *
+ * Removes at most one leading `v`, validates the result as SemVer, and
+ * falls back to `0.0.0+<first 12 hex digits of record.digest>` when no
+ * valid SemVer is present.
+ *
+ * @param declaredVersion - The raw version string from the record, or undefined.
+ * @param digest - The record's content digest in `sha256:<64 hex>` format.
+ * @returns A valid SemVer string.
+ *
+ * @public
+ */
+declare function resolveVersion(declaredVersion: string | undefined, digest: string): string;
+/**
+ * A parsed OCI skill reference.
+ *
+ * @public
+ */
+interface OciRef {
+    /** Full OCI URI: `oci://<registry>/<repository>@sha256:<hex>`. */
+    uri: string;
+    /** Registry host (and optional port). */
+    registry: string;
+    /** Repository path (may contain slashes). */
+    repository: string;
+    /** Content digest in `sha256:<64 hex>` format. */
+    digest: string;
+}
+/**
+ * Constructs a digest-addressed OCI reference URI.
+ *
+ * The returned URI has the form `oci://<registry>/<repository>@sha256:<hex>`.
+ * The provided digest must be a valid SHA-256 digest string.
+ *
+ * @param registry - Registry host (e.g., `quay.io`).
+ * @param repository - Repository path (e.g., `octo/hello-world-skill`).
+ * @param digest - Content digest in `sha256:<64 hex>` format.
+ * @returns The constructed OCI URI.
+ * @throws If the digest is invalid.
+ *
+ * @public
+ */
+declare function buildOciRef(registry: string, repository: string, digest: string): string;
+/**
+ * Parses a digest-addressed OCI reference URI.
+ *
+ * Rejects URIs that do not match the `oci://<registry>/<repository>@sha256:<hex>`
+ * pattern. When a `recordDigest` is provided, validates that the URI digest
+ * agrees with the record digest.
+ *
+ * @param uri - The OCI URI to parse.
+ * @param recordDigest - Optional record digest to verify agreement.
+ * @returns The parsed OCI reference.
+ * @throws If the URI is malformed or the digest does not agree.
+ *
+ * @public
+ */
+declare function parseOciRef(uri: string, recordDigest?: string): OciRef;
+/**
+ * A parsed npx skill reference.
+ *
+ * @public
+ */
+interface NpxRef {
+    /** Serialized reference: `<sourceUri>#<digest>`. */
+    ref: string;
+    /** The artifact source URL (HTTPS, no credentials or fragments). */
+    sourceUri: string;
+    /** Content digest in `sha256:<64 hex>` format. */
+    digest: string;
+}
+/**
+ * Constructs an npx skill reference from a verified artifact URL and digest.
+ *
+ * The reference has the form `<sourceUri>#<digest>` where `sourceUri` is an
+ * absolute HTTPS URL without credentials or fragments, and `digest` is a
+ * lowercase SHA-256 digest.
+ *
+ * Non-sensitive query parameters retain their original order.
+ *
+ * @param sourceUri - Absolute HTTPS artifact URL.
+ * @param digest - Content digest in `sha256:<64 hex>` format.
+ * @returns The serialized npx reference string.
+ * @throws If the URL contains credentials, fragments, or sensitive params,
+ *   or if the digest is invalid, or the URL is not HTTPS.
+ *
+ * @public
+ */
+declare function buildNpxRef(sourceUri: string, digest: string): string;
+/**
+ * Parses an npx skill reference.
+ *
+ * Splits at the single literal `#` separator. Validates that the URL is
+ * HTTPS, contains no credentials or fragments, and that the digest is a
+ * valid SHA-256 digest.
+ *
+ * @param ref - The serialized npx reference (`<sourceUri>#<digest>`).
+ * @returns The parsed npx reference.
+ * @throws If the reference is malformed or the URL is sensitive.
+ *
+ * @public
+ */
+declare function parseNpxRef(ref: string): NpxRef;
+
+
+
+
+
+
+
+
+
+/**
+ * Sorts skill records by stable `key` in ascending Unicode code-point order.
+ *
+ * This is the deterministic ordering required by design D2: before applying
+ * count or serialized-size limits, connectors sort records by stable `key`
+ * and include the longest prefix that fits.
+ *
+ * @public
+ */
+declare function sortRecordsByKey<T extends OciSkillRecord | NpxSkillRecord>(records: T[]): T[];
+/**
+ * Options for creating a bounded snapshot.
+ *
+ * @public
+ */
+interface BoundSnapshotOptions {
+    /** Source identity. */
+    source: SnapshotSource;
+    /** All successfully normalized records (will be sorted and bounded). */
+    records: Array<OciSkillRecord | NpxSkillRecord>;
+    /** Stable keys of skills that failed processing. */
+    failedSkillKeys: string[];
+    /**
+     * Whether discovery completed without failures or limits.
+     * When `true` and no failed keys, status is `ready`.
+     * When `false`, status is `partial`.
+     */
+    discoveryComplete: boolean;
+    /** UTC observation time. */
+    observedAt: string;
+}
+/**
+ * Creates a bounded v1 skill snapshot with deterministic ordering.
+ *
+ * Sorts records by stable key in ascending Unicode code-point order,
+ * then selects the longest prefix that fits within:
+ * - {@link MAX_SNAPSHOT_RECORDS} (1,000) records
+ * - {@link MAX_SNAPSHOT_BYTES} (5 MiB) serialized JSON
+ *
+ * If bounding removes records, the status becomes `partial` — a
+ * truncated `ready` response is never produced per design D2.
+ *
+ * Failed keys are sorted in the same ascending order.
+ *
+ * @public
+ */
+declare function boundSnapshot(options: BoundSnapshotOptions): SkillSnapshot;
+/**
+ * Creates a `loading` snapshot for a source that has not yet completed
+ * its first acquisition.
+ *
+ * @public
+ */
+declare function createLoadingSnapshot(source: SnapshotSource): SkillSnapshot;
+/**
+ * Creates a `failed` snapshot when no usable discovery result could
+ * be obtained.
+ *
+ * @public
+ */
+declare function createFailedSnapshot(source: SnapshotSource, observedAt: string): SkillSnapshot;
+
+/**
+ * Shared REST contract constants for skill connector endpoints.
+ *
+ * Each connector exposes `GET /skills/:sourceId` relative to its Backstage
+ * plugin base URL. The common catalog provider resolves the connector
+ * through Backstage discovery and authenticates with a service token whose
+ * `targetPluginId` matches the connector's registered plugin ID.
+ *
+ * ## Endpoint: GET /skills/:sourceId
+ *
+ * ### Path parameters
+ * - `sourceId` — the configured source identifier, encoded as one path
+ *   segment.
+ *
+ * ### Authentication
+ * Uses Backstage's default backend service-to-service authentication.
+ * The endpoint is not public merely because upstream registries may be
+ * public.
+ *
+ * ### Responses
+ * - **200** — returns a `SkillSnapshot` v1 JSON body.
+ *   - `Content-Type: application/json`
+ *   - The response contains one bounded snapshot with at most 1,000
+ *     records and 5 MiB of serialized JSON.
+ * - **404** — the `sourceId` is not configured on this connector.
+ *
+ * ### Consumer responsibilities
+ * The consumer bounds its response read and rejects an oversized,
+ * malformed, unsupported-version, or source-mismatched snapshot without
+ * changing that source's catalog state.
+ *
+ * @packageDocumentation
+ * @public
+ */
+/**
+ * Base path for the skills endpoint on each connector.
+ *
+ * @public
+ */
+declare const SKILLS_ENDPOINT_BASE = "/skills";
+/**
+ * Maximum response read size in bytes that consumers should accept.
+ * Matches the 5 MiB snapshot serialized-size bound.
+ *
+ * @public
+ */
+declare const MAX_RESPONSE_BYTES: number;
+
+/**
+ * Reusable OCI and npx contract fixtures for connector and provider tests.
+ *
+ * @packageDocumentation
+ */
+
+
+
+
+
+
+
+
+/**
+ * OCI source fixture for contract tests.
+ *
+ * @public
+ */
+declare const ociSource: SnapshotSource;
+/**
+ * npx source fixture for contract tests.
+ *
+ * @public
+ */
+declare const npxSource: SnapshotSource;
+/**
+ * A valid OCI skill record with full metadata.
+ *
+ * @public
+ */
+declare const validOciRecordFull: OciSkillRecord;
+/**
+ * A valid OCI record with only required fields.
+ *
+ * @public
+ */
+declare const validOciRecordMinimal: OciSkillRecord;
+/**
+ * A valid OCI record with empty extensions object.
+ *
+ * @public
+ */
+declare const validOciRecordEmptyExtensions: OciSkillRecord;
+/**
+ * A valid npx skill record with full metadata.
+ *
+ * @public
+ */
+declare const validNpxRecordFull: NpxSkillRecord;
+/**
+ * A valid npx record with only required fields.
+ *
+ * @public
+ */
+declare const validNpxRecordMinimal: NpxSkillRecord;
+/**
+ * A valid npx record with a query-string-bearing source URI.
+ *
+ * @public
+ */
+declare const validNpxRecordWithQuery: NpxSkillRecord;
+/**
+ * A valid ready OCI snapshot.
+ *
+ * @public
+ */
+declare const validOciSnapshotReady: SkillSnapshot;
+/**
+ * A valid ready npx snapshot.
+ *
+ * @public
+ */
+declare const validNpxSnapshotReady: SkillSnapshot;
+/**
+ * A valid loading snapshot.
+ *
+ * @public
+ */
+declare const validLoadingSnapshot: SkillSnapshot;
+/**
+ * A valid partial snapshot with failed keys.
+ *
+ * @public
+ */
+declare const validPartialSnapshot: SkillSnapshot;
+/**
+ * A valid failed snapshot.
+ *
+ * @public
+ */
+declare const validFailedSnapshot: SkillSnapshot;
+/**
+ * A valid partial snapshot with no records and no failed keys.
+ *
+ * @public
+ */
+declare const validPartialEmptySnapshot: SkillSnapshot;
+/**
+ * A valid ready snapshot with zero records (successful empty discovery).
+ *
+ * @public
+ */
+declare const validReadyEmptySnapshot: SkillSnapshot;
+/**
+ * Record with empty key.
+ *
+ * @public
+ */
+declare const invalidRecordEmptyKey: OciSkillRecord;
+/**
+ * Record with malformed digest (uppercase).
+ *
+ * @public
+ */
+declare const invalidRecordBadDigest: OciSkillRecord;
+/**
+ * Record with truncated digest.
+ *
+ * @public
+ */
+declare const invalidRecordShortDigest: OciSkillRecord;
+/**
+ * npx record with OCI extension (source mismatch).
+ *
+ * @public
+ */
+declare const invalidNpxRecordWithOciExtension: NpxSkillRecord;
+/**
+ * OCI record with npx extension (source mismatch).
+ *
+ * @public
+ */
+declare const invalidOciRecordWithNpxExtension: OciSkillRecord;
+/**
+ * OCI record with unknown extension key.
+ *
+ * @public
+ */
+declare const invalidOciRecordUnknownExtKey: OciSkillRecord;
+/**
+ * Snapshot with unsupported schema version.
+ *
+ * @public
+ */
+declare const invalidSnapshotBadVersion: unknown;
+/**
+ * Snapshot claiming ready with failed keys.
+ *
+ * @public
+ */
+declare const invalidSnapshotReadyWithFailedKeys: unknown;
+/**
+ * Snapshot with duplicate skill keys.
+ *
+ * @public
+ */
+declare const invalidSnapshotDuplicateKeys: unknown;
+/**
+ * Snapshot with overlapping skill and failed keys.
+ *
+ * @public
+ */
+declare const invalidSnapshotOverlappingKeys: unknown;
+/**
+ * Loading snapshot with non-null observedAt.
+ *
+ * @public
+ */
+declare const invalidLoadingWithObservedAt: unknown;
+/**
+ * Loading snapshot with skills.
+ *
+ * @public
+ */
+declare const invalidLoadingWithSkills: unknown;
+/**
+ * Failed snapshot with skills.
+ *
+ * @public
+ */
+declare const invalidFailedWithSkills: unknown;
+/**
+ * Snapshot with non-UTC timestamp.
+ *
+ * @public
+ */
+declare const invalidSnapshotNonUtcTimestamp: unknown;
+
+/**
+ * Shared v1 skill record and snapshot contract for skill connectors
+ * and the common catalog provider.
+ *
+ * This library owns schemas, validation, and pure helpers. It performs
+ * no network, scheduler, database, or catalog operations.
+ *
+ * @packageDocumentation
+ */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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 };