@adea-ai/plugins 4.0.0 → 4.0.6

package/src/plugin-skips.ts

@@ -0,0 +1,110 @@
+import type { MarketplacePluginEntry } from './sources.js'
+import type { ResolvedSource } from './source-resolution.js'
+import { stablePluginId } from './taxonomy.js'
+
+export type PluginSkipReasonCode =
+  | 'GIT_SUBMODULE_UNSUPPORTED'
+  | 'PLUGIN_FILE_TOO_LARGE'
+  | 'PLUGIN_FILE_UNAVAILABLE'
+  | 'PLUGIN_MANIFEST_INVALID'
+  | 'PLUGIN_PATH_NOT_FOUND'
+  | 'PLUGIN_SCHEMA_INVALID'
+  | 'PLUGIN_SIZE_POLICY'
+  | 'PLUGIN_SOURCE_UNAVAILABLE'
+  | 'PLUGIN_TOO_LARGE'
+  | 'PLUGIN_TOO_MANY_FILES'
+  | 'SNAPSHOT_PATH_INVALID'
+  | 'SYMLINK_ESCAPE'
+
+export interface SkippedPlugin {
+  readonly sourceId: string
+  readonly pluginId: string
+  readonly pluginName: string
+  readonly reasonCode: PluginSkipReasonCode
+  readonly securityReason: string
+  readonly incompleteContent: true
+  readonly paths: readonly string[]
+}
+
+export class PluginSafetyError extends Error {
+  constructor(
+    readonly reasonCode: PluginSkipReasonCode,
+    readonly paths: readonly string[]
+  ) {
+    super(`${reasonCode}${paths.length > 0 ? `: ${paths.join(',')}` : ''}`)
+    this.name = 'PluginSafetyError'
+  }
+}
+
+const pluginSkipReasons: Readonly<Record<PluginSkipReasonCode, string>> = {
+  GIT_SUBMODULE_UNSUPPORTED:
+    'The plugin contains a Git submodule, so the catalog excludes it rather than traversing an unpinned repository boundary.',
+  PLUGIN_FILE_TOO_LARGE:
+    'The plugin contains a file over the configured size limit, so the catalog excludes the plugin before publication.',
+  PLUGIN_FILE_UNAVAILABLE:
+    'A plugin file could not be fetched from upstream after retries, so the catalog excludes the plugin rather than publishing partial content.',
+  PLUGIN_MANIFEST_INVALID:
+    'The plugin manifest is malformed, so the catalog excludes the plugin before consuming its metadata.',
+  PLUGIN_PATH_NOT_FOUND:
+    'The declared plugin path does not exist at the pinned commit, so the catalog excludes the plugin.',
+  PLUGIN_SCHEMA_INVALID:
+    'The normalized plugin record exceeds the published catalog schema, so the catalog excludes it before publication.',
+  PLUGIN_SIZE_POLICY:
+    'The plugin exceeds the configured size policy, so the catalog excludes it before publication.',
+  PLUGIN_SOURCE_UNAVAILABLE:
+    'The plugin repository tree could not be fetched from upstream after retries, so the catalog excludes the plugin rather than publishing partial content.',
+  PLUGIN_TOO_LARGE:
+    'The plugin exceeds the configured aggregate size limit, so the catalog excludes it before publication.',
+  PLUGIN_TOO_MANY_FILES:
+    'The plugin exceeds the configured file-count limit, so the catalog excludes it before publication.',
+  SNAPSHOT_PATH_INVALID:
+    'The plugin snapshot contains an unsafe path, so the catalog excludes it rather than allowing repository escape.',
+  SYMLINK_ESCAPE:
+    'The plugin snapshot contains symlinks; symlinks are never followed, so the catalog excludes the plugin.',
+}
+
+export function createSkippedPlugin(
+  source: ResolvedSource,
+  entry: MarketplacePluginEntry,
+  error: unknown
+): SkippedPlugin | undefined {
+  const parsed =
+    error instanceof PluginSafetyError
+      ? { reasonCode: error.reasonCode, paths: error.paths }
+      : parsePluginSafetyError(error)
+  if (!parsed) return undefined
+  return {
+    sourceId: source.config.sourceId,
+    pluginId: stablePluginId(source.config.sourceId, entry.name),
+    pluginName: entry.name,
+    reasonCode: parsed.reasonCode,
+    securityReason: pluginSkipReasons[parsed.reasonCode],
+    incompleteContent: true,
+    paths: [...new Set(parsed.paths)].toSorted(),
+  }
+}
+
+function parsePluginSafetyError(
+  error: unknown
+): { reasonCode: PluginSkipReasonCode; paths: readonly string[] } | undefined {
+  const message = error instanceof Error ? error.message : String(error)
+  const match = /^([A-Z_]+)(?::\s?(.*))?$/.exec(message)
+  if (!match) return undefined
+  const reasonCode = match[1] as PluginSkipReasonCode
+  if (!(reasonCode in pluginSkipReasons)) return undefined
+  return {
+    reasonCode,
+    paths: match[2]
+      ? match[2]
+          .split(',')
+          .map((path) => path.trim())
+          .filter(Boolean)
+      : [],
+  }
+}
+
+export const UPSTREAM_WEATHER_SKIP_CODES: ReadonlySet<PluginSkipReasonCode> = new Set([
+  'PLUGIN_SOURCE_UNAVAILABLE',
+  'PLUGIN_FILE_UNAVAILABLE',
+  'PLUGIN_PATH_NOT_FOUND',
+])

package/src/policy.ts

@@ -0,0 +1,39 @@
+import { PACKAGE_LIMITS } from './agent-plugins-schema.js'
+import { canonicalRepositoryUrl } from './sources.js'
+
+export interface CatalogPolicy {
+  readonly allowedRepositoryProtocols: readonly string[]
+  readonly allowedRepositoryHosts: readonly string[]
+  readonly maxFilesPerPlugin: number
+  readonly maxBytesPerPlugin: number
+  readonly maxFileBytes: number
+  readonly maxMarketplacePlugins: number
+  readonly denyExecutableLifecycleScripts: boolean
+  readonly publishRequiresCompleteContent: boolean
+  readonly sensitiveCapabilityTypes: readonly string[]
+}
+
+export const DEFAULT_POLICY: CatalogPolicy = {
+  allowedRepositoryProtocols: ['https:'],
+  allowedRepositoryHosts: ['github.com', 'www.github.com'],
+  ...PACKAGE_LIMITS,
+  maxMarketplacePlugins: 4096,
+  denyExecutableLifecycleScripts: true,
+  publishRequiresCompleteContent: false,
+  sensitiveCapabilityTypes: [
+    'mcp-server',
+    'connector',
+    'hook',
+    'browser',
+    'scheduled-task',
+    'executable',
+  ],
+}
+
+export function assertRepositoryAllowed(repositoryUrl: string, policy: CatalogPolicy): void {
+  const parsed = new URL(canonicalRepositoryUrl(repositoryUrl))
+  if (!policy.allowedRepositoryProtocols.includes(parsed.protocol))
+    throw new Error(`GIT_PROTOCOL_POLICY: ${parsed.protocol}`)
+  if (!policy.allowedRepositoryHosts.includes(parsed.hostname.toLowerCase()))
+    throw new Error(`GIT_HOST_POLICY: ${parsed.hostname}`)
+}

package/src/portable-catalog.test.ts

@@ -17,7 +17,6 @@ import type { HarnessProfile } from './agent-plugins-schema.js'
 import { snapshotFromDirectory } from './index.js'
 import {
   copyDependency,
-  nodeCandidates,
   packageLifecycleScripts,
   selectPinnedNode,
   withPackedConsumerFixture,
@@ -612,10 +611,6 @@ it('qualifies the compiled artifact only on Node 24', async () => {
     assert.equal(selectPinnedNode([node20, node24]), node24)
     assert.throws(() => selectPinnedNode([node20]), /needs Node 24/)
     assert.throws(() => selectPinnedNode([]), /needs Node 24/)
-    // The discovery ends with the `node` on PATH, which is where a CI
-    // runner's pinned setup action puts Node 24.
-    const candidates = nodeCandidates()
-    assert.ok(candidates.includes('node'))
   } finally {
     await rm(directory, { recursive: true, force: true })
   }

package/src/portable-catalog.ts

@@ -1,22 +1,13 @@
-import { CatalogSchema, HarnessSchema, type Catalog, type Plugin } from './schema.js'
-import {
-  orderLeadingPlugins,
-  synchronize,
-  createArtifacts,
-  verifyArtifacts,
-  digest,
-  type SyncInput,
-  type SyncResult,
-  type ReleaseTransform,
-} from './index.js'
-import {
-  compileAgentPackage,
-  verifyAgentPackage,
-  NORMALIZER_VERSION,
-} from './agent-plugins-catalog.js'
-import { CATALOG_CONTRACT_VERSION } from './index.js'
+import { compileAgentPackage, verifyAgentPackage } from './agent-plugins-catalog.js'
+import { NORMALIZER_VERSION, PACKAGE_METADATA_KEY } from './agent-plugins-schema.js'
+
+import { CATALOG_CONTRACT_VERSION, type ReleaseTransform } from './plugin-release.js'
+import { HarnessSchema, type Catalog, type Plugin } from './schema.js'
+import { verifyPortableCatalog } from './portable-verify.js'
+import { synchronize, type SyncInput, type SyncResult } from './synchronize.js'
+
+export { PACKAGE_METADATA_KEY, verifyPortableCatalog }
 
-export const PACKAGE_METADATA_KEY = 'agentPlugins'
 function currentContract(catalog: Catalog | undefined): boolean {
   return (
     !!catalog &&
@@ -96,10 +87,14 @@ export async function synchronizePortable(options: SyncInput): Promise<SyncResul
   }
   // Compile while each upstream snapshot is already in scope. Do not retain all
   // marketplace file bytes or fetch every package a second time after cataloging.
-  const input = {
+  const input: SyncInput = {
     ...options,
     metadataOnly: options.metadataOnly === true || options.dryRun === true,
     transformRelease,
+    releaseCompatibility: (release) => {
+      const pkg = release.releaseMetadata[PACKAGE_METADATA_KEY]
+      return pkg ? compatibility(verifyAgentPackage(pkg)) : undefined
+    },
   }
   let result = await synchronize(input)
   if (
@@ -112,128 +107,6 @@ export async function synchronizePortable(options: SyncInput): Promise<SyncResul
     // need not change for a format migration, and dry runs still never publish.
     result = await synchronize({ ...input, fromLock: input.existingLock })
   }
-  if (!result.catalog || !result.lock || input.metadataOnly) return result
-  const plugins: Plugin[] = []
-  for (const plugin of result.catalog.plugins) {
-    const releases = plugin.availableReleases
-    const selected = releases.find((release) => release.releaseId === plugin.currentReleaseId)
-    const pkg = selected?.releaseMetadata[PACKAGE_METADATA_KEY]
-    plugins.push({
-      ...plugin,
-      availableReleases: releases,
-      ...(pkg ? { harnessCompatibility: compatibility(verifyAgentPackage(pkg)) } : {}),
-    })
-  }
-  const { catalogId: _oldId, ...old } = CatalogSchema.parse(result.catalog)
-  // Ordering is applied before the catalog ID is computed so the emitted
-  // identifier digests the final plugin order: each category's leading
-  // products head the list.
-  const ordered = orderLeadingPlugins({ ...old, plugins }, options.leading)
-  const catalog = CatalogSchema.parse({
-    ...ordered,
-    catalogId: `catalog:${digest(ordered).slice(7)}`,
-  })
-  verifyPortableCatalog(catalog)
-  const artifacts = createArtifacts(catalog, result.lock, {
-    ...(options.leading ? { leading: options.leading } : {}),
-    ...(options.topCount !== undefined ? { topCount: options.topCount } : {}),
-    ...(options.productPreference ? { productPreference: options.productPreference } : {}),
-    // Without this the shipped artifacts cannot advertise where they are
-    // published, so brand marks and the browsing index lose their URLs. This
-    // path replaces the artifacts the legacy compiler already produced, which is
-    // why it must repeat every option it needs.
-    ...(options.publicationRepositoryUrl
-      ? { publicationRepositoryUrl: options.publicationRepositoryUrl }
-      : {}),
-    ...(options.publicationAssetsBaseUrl
-      ? { publicationAssetsBaseUrl: options.publicationAssetsBaseUrl }
-      : {}),
-    ...(options.publicationCatalogsBaseUrl
-      ? { publicationCatalogsBaseUrl: options.publicationCatalogsBaseUrl }
-      : {}),
-    curationDiagnostics: (options.mode ?? 'live') !== 'offline',
-  })
-  verifyArtifacts(artifacts)
-  const changed = catalog.plugins
-    .filter((plugin) => {
-      const prior = input.existingCatalog?.plugins.find((item) => item.pluginId === plugin.pluginId)
-      return prior && digest(prior) !== digest(plugin)
-    })
-    .map((plugin) => plugin.pluginId)
-  return {
-    ...result,
-    catalog,
-    artifacts,
-    changeReport: {
-      ...result.changeReport,
-      changedPlugins: [...new Set([...result.changeReport.changedPlugins, ...changed])].toSorted(),
-    },
-  }
-}
-
-/**
- * A single-line summary of why a release's package descriptor was refused.
- *
- * The schema's own failure is a structured issue list; the catalog's refusal
- * contract is one typed line. The first issue is kept as the detail, because
- * it names the field that was wrong.
- */
-function describeProvenanceFailure(error: unknown): string {
-  const issues = (error as { issues?: unknown }).issues
-  if (Array.isArray(issues) && issues.length > 0) {
-    const first = issues[0] as { path?: unknown; message?: unknown }
-    const path = Array.isArray(first.path) ? first.path.join('.') : ''
-    const message = typeof first.message === 'string' ? first.message : ''
-    return [path, message].filter(Boolean).join(': ').replace(/\s+/g, ' ').slice(0, 200)
-  }
-  return error instanceof Error
-    ? error.message.replace(/\s+/g, ' ').slice(0, 200)
-    : 'the descriptor is not a package recipe'
-}
-
-export function verifyPortableCatalog(catalog: Catalog, requirePortable = false): void {
-  const { catalogId, ...body } = CatalogSchema.parse(catalog)
-  if (catalogId !== `catalog:${digest(body).slice(7)}`) throw new Error('CATALOG_ID_MISMATCH')
-  const ids = new Set<string>()
-  for (const plugin of catalog.plugins) {
-    if (ids.has(plugin.pluginId)) throw new Error('DUPLICATE_PLUGIN_ID')
-    ids.add(plugin.pluginId)
-    const releases = new Set(plugin.availableReleases.map((release) => release.releaseId))
-    if (releases.size !== plugin.availableReleases.length || !releases.has(plugin.currentReleaseId))
-      throw new Error('RELEASE_SELECTION_INVALID')
-  }
-  for (const plugin of catalog.plugins)
-    for (const release of plugin.availableReleases) {
-      if (requirePortable && release.contentResolution !== 'complete')
-        throw new Error('COMPLETE_SOURCE_REQUIRED')
-      const descriptor = release.releaseMetadata[PACKAGE_METADATA_KEY]
-      if (descriptor === undefined) {
-        if (requirePortable && release.contentResolution === 'complete')
-          throw new Error(`PORTABLE_RESYNC_REQUIRED: ${plugin.pluginId}`)
-        continue
-      }
-      let pkg: ReturnType<typeof verifyAgentPackage>
-      try {
-        pkg = verifyAgentPackage(descriptor)
-      } catch (error) {
-        // A consumer imports a catalog it did not compile, so a malformed
-        // provenance descriptor is an IMPORT failure, and it must be refused
-        // the way every other failure here is refused: one typed, single-line
-        // reason that names the plugin. The schema's own multi-line issue
-        // dump is not a refusal a consumer can match on.
-        throw new Error(
-          `PACKAGE_PROVENANCE_INVALID: ${plugin.pluginId} (${describeProvenanceFailure(error)})`,
-          { cause: error }
-        )
-      }
-      if (
-        release.contentResolution !== 'complete' ||
-        pkg.sourceDigest !== release.canonicalContentDigest
-      )
-        throw new Error(`PACKAGE_PROVENANCE_MISMATCH: ${plugin.pluginId}`)
-      const sourcePaths = new Set(release.fileIndex)
-      for (const file of pkg.files)
-        if (file.action === 'copy' && !sourcePaths.has(file.sourcePath))
-          throw new Error(`PACKAGE_SOURCE_FILE_MISSING: ${plugin.pluginId}`)
-    }
+  if (result.catalog && !input.metadataOnly) verifyPortableCatalog(result.catalog)
+  return result
 }

package/src/portable-verify.ts

@@ -0,0 +1,71 @@
+import { verifyAgentPackage } from './agent-plugins-catalog.js'
+import { PACKAGE_METADATA_KEY } from './agent-plugins-schema.js'
+import { contentId } from './digest.js'
+import { CatalogSchema, type Catalog } from './schema.js'
+
+/**
+ * A single-line summary of why a release's package descriptor was refused.
+ *
+ * The schema's own failure is a structured issue list; the catalog's refusal
+ * contract is one typed line. The first issue is kept as the detail, because
+ * it names the field that was wrong.
+ */
+function describeProvenanceFailure(error: unknown): string {
+  const issues = (error as { issues?: unknown }).issues
+  if (Array.isArray(issues) && issues.length > 0) {
+    const first = issues[0] as { path?: unknown; message?: unknown }
+    const path = Array.isArray(first.path) ? first.path.join('.') : ''
+    const message = typeof first.message === 'string' ? first.message : ''
+    return [path, message].filter(Boolean).join(': ').replace(/\s+/g, ' ').slice(0, 200)
+  }
+  return error instanceof Error
+    ? error.message.replace(/\s+/g, ' ').slice(0, 200)
+    : 'the descriptor is not a package recipe'
+}
+
+export function verifyPortableCatalog(catalog: Catalog, requirePortable = false): void {
+  const { catalogId, ...body } = CatalogSchema.parse(catalog)
+  if (catalogId !== contentId('catalog', body)) throw new Error('CATALOG_ID_MISMATCH')
+  const ids = new Set<string>()
+  for (const plugin of catalog.plugins) {
+    if (ids.has(plugin.pluginId)) throw new Error('DUPLICATE_PLUGIN_ID')
+    ids.add(plugin.pluginId)
+    const releases = new Set(plugin.availableReleases.map((release) => release.releaseId))
+    if (releases.size !== plugin.availableReleases.length || !releases.has(plugin.currentReleaseId))
+      throw new Error('RELEASE_SELECTION_INVALID')
+  }
+  for (const plugin of catalog.plugins)
+    for (const release of plugin.availableReleases) {
+      if (requirePortable && release.contentResolution !== 'complete')
+        throw new Error('COMPLETE_SOURCE_REQUIRED')
+      const descriptor = release.releaseMetadata[PACKAGE_METADATA_KEY]
+      if (descriptor === undefined) {
+        if (requirePortable && release.contentResolution === 'complete')
+          throw new Error(`PORTABLE_RESYNC_REQUIRED: ${plugin.pluginId}`)
+        continue
+      }
+      let pkg: ReturnType<typeof verifyAgentPackage>
+      try {
+        pkg = verifyAgentPackage(descriptor)
+      } catch (error) {
+        // A consumer imports a catalog it did not compile, so a malformed
+        // provenance descriptor is an IMPORT failure, and it must be refused
+        // the way every other failure here is refused: one typed, single-line
+        // reason that names the plugin. The schema's own multi-line issue
+        // dump is not a refusal a consumer can match on.
+        throw new Error(
+          `PACKAGE_PROVENANCE_INVALID: ${plugin.pluginId} (${describeProvenanceFailure(error)})`,
+          { cause: error }
+        )
+      }
+      if (
+        release.contentResolution !== 'complete' ||
+        pkg.sourceDigest !== release.canonicalContentDigest
+      )
+        throw new Error(`PACKAGE_PROVENANCE_MISMATCH: ${plugin.pluginId}`)
+      const sourcePaths = new Set(release.fileIndex)
+      for (const file of pkg.files)
+        if (file.action === 'copy' && !sourcePaths.has(file.sourcePath))
+          throw new Error(`PACKAGE_SOURCE_FILE_MISSING: ${plugin.pluginId}`)
+    }
+}

package/src/publication.test.ts

@@ -66,7 +66,7 @@ describe('catalog publication addresses', () => {
     )
   })
 
-  test('only a GitHub repository can be addressed', () => {
+  test('refuses a repository URL it cannot address', () => {
     expect(() => catalogAssetsBaseUrl('https://example.com/adea-ai/plugins')).toThrow(
       'REPOSITORY_URL_UNSUPPORTED'
     )
@@ -115,3 +115,31 @@ describe('staged asset audit', () => {
     expect(audit.unstaged).toEqual(['icon-unstaged.png'])
   })
 })
+
+describe('GitLab publication URLs', () => {
+  const repository = 'https://gitlab.com/adea-ai/ade/plugins'
+
+  test('addresses the branch through GitLab raw URLs in nested groups', () => {
+    expect(catalogAssetsBaseUrl(repository)).toBe(
+      'https://gitlab.com/adea-ai/ade/plugins/-/raw/catalog-assets'
+    )
+    expect(latestPointerUrl(`${repository}.git`)).toBe(
+      'https://gitlab.com/adea-ai/ade/plugins/-/raw/catalog-assets/catalog-latest.v1.json'
+    )
+  })
+
+  test('still addresses GitHub so the forge can switch back', () => {
+    expect(catalogAssetsBaseUrl('https://github.com/adea-ai/plugins')).toBe(
+      'https://raw.githubusercontent.com/adea-ai/plugins/catalog-assets'
+    )
+  })
+
+  test('rejects other hosts and traversal', () => {
+    expect(() => catalogAssetsBaseUrl('https://example.com/a/b')).toThrow(
+      'REPOSITORY_URL_UNSUPPORTED'
+    )
+    expect(() => catalogAssetsBaseUrl('https://gitlab.com/a/../b')).toThrow(
+      'REPOSITORY_URL_INVALID'
+    )
+  })
+})

package/src/publication.ts

@@ -1,3 +1,5 @@
+import { CatalogSchema } from './schema.js'
+
 /**
  * Where a published catalog lives, and the URLs that address it.
  *
@@ -9,10 +11,11 @@
  * that slot, so no version is ever the one a visitor sees first.
  *
  * The branch gives each catalog an immutable path — `catalogs/<catalogId>/…`,
- * where `catalogId` is the canonical digest of the catalog itself — so a
- * pinned URL is immutable by construction, exactly as a content-addressed
- * release tag was, and `raw.githubusercontent.com` serves it with permissive
- * CORS so a browser can fetch it directly.
+ * where `catalogId` is the canonical digest of the catalog itself. The
+ * publisher must reject replacement of existing snapshot bytes. GitLab raw URLs
+ * serve the branch to servers and image tags; unlike
+ * `raw.githubusercontent.com` they send no CORS header, so a browser `fetch`
+ * needs a same-origin proxy.
  */
 
 export const publishedArtifactNames = [
@@ -63,11 +66,9 @@ export interface StagedAssetAudit {
 /**
  * Audits the bytes this build staged against what it declared.
  *
- * A content-addressed path removes the comparison the release audit used to
- * perform: a snapshot published at `catalogs/<catalogId>/` can only hold this
- * catalog's bytes, because any different build has a different `catalogId` and
- * therefore a different path. What survives is the check that cannot be
- * delegated to the path — that the bytes exist here at all.
+ * This checks that the declared bytes exist here at all. Publication must
+ * separately compare the complete staged snapshot with any existing snapshot:
+ * companion artifacts can differ without changing the catalog identity.
  */
 export function auditStagedAssets(input: {
   readonly declared: readonly DeclaredAsset[]
@@ -95,14 +96,13 @@ export interface PublicationPlan {
 /**
  * The 64-hex digest a `catalog:<hex>` identity is addressed by.
  *
- * A catalog identity names its own bytes, so this is also what makes the
- * snapshot path immutable: any build that produced different content has a
- * different identity and cannot write over this one.
+ * A catalog identity names the catalog content. The publisher must also guard
+ * the snapshot path against changes to companion artifacts under the same ID.
  */
 export function catalogIdSuffix(catalogId: string): string {
-  const match = /^catalog:([a-f0-9]{64})$/.exec(catalogId)
-  if (!match) throw new Error(`CATALOG_ID_INVALID: ${catalogId}`)
-  return match[1] as string
+  if (!CatalogSchema.shape.catalogId.safeParse(catalogId).success)
+    throw new Error(`CATALOG_ID_INVALID: ${catalogId}`)
+  return catalogId.slice('catalog:'.length)
 }
 
 /**
@@ -110,7 +110,10 @@ export function catalogIdSuffix(catalogId: string): string {
  * catalog pointer.
  */
 export function catalogAssetsBaseUrl(repositoryUrl: string): string {
-  return `https://raw.githubusercontent.com/${repositorySlug(repositoryUrl)}/${catalogAssetsBranch}`
+  const { host, path } = repositoryLocation(repositoryUrl)
+  return host === 'gitlab.com'
+    ? `https://gitlab.com/${path}/-/raw/${catalogAssetsBranch}`
+    : `https://raw.githubusercontent.com/${path}/${catalogAssetsBranch}`
 }
 
 /** Root of one catalog's immutable artifacts, content-addressed by identity. */
@@ -137,6 +140,11 @@ export function createPublicationPlan(input: {
   }
 }
 
+/** A flat file name that is safe as both a local file and a URL path segment. */
+export function isPublishedName(name: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(name)
+}
+
 /**
  * Immutable URL for one artifact of one catalog.
  *
@@ -150,22 +158,30 @@ export function immutableAssetUrl(
   catalogId: string,
   assetName: string
 ): string {
-  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(assetName))
-    throw new Error(`ASSET_NAME_INVALID: ${assetName}`)
+  if (!isPublishedName(assetName)) throw new Error(`ASSET_NAME_INVALID: ${assetName}`)
   return `${catalogSnapshotBaseUrl(repositoryUrl, catalogId)}/${assetName}`
 }
 
-function repositorySlug(repositoryUrl: string): string {
+function repositoryLocation(repositoryUrl: string): {
+  readonly host: 'github.com' | 'gitlab.com'
+  readonly path: string
+} {
   let parsed: URL
   try {
     parsed = new URL(repositoryUrl)
   } catch {
     throw new Error(`REPOSITORY_URL_INVALID: ${repositoryUrl}`)
   }
-  if (parsed.protocol !== 'https:' || parsed.hostname !== 'github.com')
+  const host = parsed.hostname
+  if (parsed.protocol !== 'https:' || (host !== 'github.com' && host !== 'gitlab.com'))
     throw new Error(`REPOSITORY_URL_UNSUPPORTED: ${repositoryUrl}`)
   const path = parsed.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '')
-  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(path))
+  // GitLab projects can sit in nested groups; GitHub is always owner/repo.
+  const shape =
+    host === 'gitlab.com'
+      ? /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+$/
+      : /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/
+  if (!shape.test(path) || path.split('/').some((part) => part === '.' || part === '..'))
     throw new Error(`REPOSITORY_URL_INVALID: ${repositoryUrl}`)
-  return path
+  return { host, path }
 }

package/src/published-output.ts

@@ -0,0 +1,60 @@
+import type { GeneratedArtifacts } from './artifacts.js'
+import { byteDigest } from './digest.js'
+import { parseIntegrityManifest, type PublishedAsset } from './integrity-manifest.js'
+import { verifyPortableCatalog } from './portable-verify.js'
+import { parseCatalog, type Catalog } from './schema.js'
+import { readStagedFile } from './staged-file.js'
+import { verifyArtifacts } from './verify-artifacts.js'
+
+/**
+ * Reads a published artifact set. `integrity.json` is the file list, so the
+ * consumer shards can grow with the category configuration.
+ */
+export async function readArtifacts(directory: string): Promise<GeneratedArtifacts> {
+  const integrity = (await readStagedFile(directory, 'integrity.json')).toString('utf8')
+  const { files } = parseIntegrityManifest(JSON.parse(integrity))
+  const names = Object.keys(files).toSorted()
+  const values = await Promise.all(
+    names.map(
+      async (name) => [name, (await readStagedFile(directory, name)).toString('utf8')] as const
+    )
+  )
+  return Object.fromEntries([
+    ...values,
+    ['integrity.json', integrity],
+  ]) as unknown as GeneratedArtifacts
+}
+
+/** Verifies an artifact set and returns its catalog, checked as a portable catalog. */
+export function verifiedCatalog(artifacts: GeneratedArtifacts, requirePortable = false): Catalog {
+  verifyArtifacts(artifacts)
+  const catalog = parseCatalog(JSON.parse(artifacts['catalog.v1.json']))
+  verifyPortableCatalog(catalog, requirePortable)
+  return catalog
+}
+
+/** The mirrored marks `integrity.json` declares, or undefined for a snapshot without any. */
+export function declaredAssets(
+  artifacts: GeneratedArtifacts
+): readonly PublishedAsset[] | undefined {
+  return parseIntegrityManifest(JSON.parse(artifacts['integrity.json'])).assets
+}
+
+/** Compares staged mark bytes in `directory` with the digests they were declared with. */
+export async function checkStagedAssets(
+  directory: string,
+  declared: readonly PublishedAsset[]
+): Promise<{ readonly missing: readonly string[]; readonly mismatched: readonly string[] }> {
+  const missing: string[] = []
+  const mismatched: string[] = []
+  for (const asset of declared) {
+    const bytes = await readStagedFile(directory, asset.name).catch((error: unknown) => {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+      throw error
+    })
+    if (!bytes) missing.push(asset.name)
+    else if (byteDigest(bytes) !== asset.digest || bytes.byteLength !== asset.bytes)
+      mismatched.push(asset.name)
+  }
+  return { missing, mismatched }
+}