Skip to content

armgit / orca

Public Imported from GitHub
0

Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

12.5 KB
Raw Blame
import { z } from 'zod'
import { safePluginDisplayText } from '../manifest/plugin-display-text'
import { isAllowedPluginGitUrl } from '../installation/plugin-install-lockfile'
import { isQualifiedPluginKey } from '../manifest/plugin-manifest'
import { pluginCatalogReleaseSchema } from './plugin-catalog-release'
import { pluginFieldDoc, PLUGIN_MANIFEST_V2_SINCE } from '../manifest/plugin-schema-field-docs'
import {
  isPluginRepositoryPath,
  PLUGIN_REPOSITORY_PATH_RE
} from '../installation/plugin-path-safety'
import { isReservedPluginPublisher } from './plugin-publisher-reservation'

const NEXT = PLUGIN_MANIFEST_V2_SINCE

// Why frozen: v1 entries are strict, so shipped clients reject any new field. New catalogs live
// in orca-catalog.json (plugin-catalog.ts); this file is generated from it for old clients.
export const PLUGIN_MARKETPLACE_FILENAME = 'orca-marketplace.json'
export const PLUGIN_MARKETPLACE_ENTRY_LIMIT = 2_048
export const PLUGIN_MARKETPLACE_CATEGORY_LIMIT = 16

export const OFFICIAL_PLUGIN_PUBLISHER = 'stablyai'
export const OFFICIAL_PLUGIN_ID_PREFIX = 'orca-'
export const OFFICIAL_MARKETPLACE_OWNER = 'stablyai'
export const OFFICIAL_MARKETPLACE_REPOSITORY = 'orca-plugins'

// Why: skill contributions are not supported, so a plugin declaring one fails to install.
// Shared catalogs this build does not control still list such packs; hide them so users never
// reach a dead install.
export const UNSUPPORTED_MARKETPLACE_CATEGORIES: readonly string[] = ['skills']

export function isMarketplaceListingSupported(categories: readonly string[]): boolean {
  return !categories.some((category) => UNSUPPORTED_MARKETPLACE_CATEGORIES.includes(category))
}

export const marketplaceOwnerSchema = z
  .string()
  .min(1)
  .max(128)
  .regex(/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/, 'invalid marketplace owner')

export const marketplaceCategorySchema = z
  .string()
  .min(1)
  .max(64)
  .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'categories must be lowercase slugs')

const gitSourceFields = {
  kind: z.literal('git').meta(pluginFieldDoc('Source kind. Only `git` is supported.', NEXT)),
  url: z
    .string()
    .trim()
    .min(1)
    .max(32 * 1024)
    .refine(isAllowedPluginGitUrl, 'git URL must use HTTPS or SSH')
    .meta(
      pluginFieldDoc('HTTPS or SSH URL of the plugin repository.', NEXT, [
        'https://github.com/acme/orca-gleam-syntax.git'
      ])
    ),
  // Why: marketplace installs must first resolve a named ref to an exact
  // commit; an omitted remote default would make the listing irreproducible.
  ref: z
    .string()
    .trim()
    .min(1)
    .max(4_096)
    .meta(
      pluginFieldDoc(
        'Branch or tag the author publishes from. Each release pins an exact commit.',
        NEXT,
        ['main']
      )
    )
}

export const pluginMarketplaceGitSourceSchema = z.strictObject(gitSourceFields)

// Why v2 only: the frozen v1 file cannot carry it, and an old client would install the repository root.
const catalogGitSourceFields = {
  ...gitSourceFields,
  path: z
    .string()
    .max(1_024)
    .regex(PLUGIN_REPOSITORY_PATH_RE, 'must be a relative directory using / without . or ..')
    .refine(
      (path) => !PLUGIN_REPOSITORY_PATH_RE.test(path) || isPluginRepositoryPath(path),
      'path segment is a Windows reserved device name'
    )
    .optional()
    .meta(
      pluginFieldDoc(
        'Directory inside the repository that holds `orca-plugin.json`, so one repository can publish many plugins. Use `/` separators, with no leading `/`, `.` or `..`. Omit when the plugin is the repository root.',
        NEXT,
        ['plugins/gleam-syntax']
      )
    )
}

// Why strip-unknown in v2: a later optional source field must not make older clients drop the entry.
export const catalogV2GitSourceSchema = z
  .object(catalogGitSourceFields)
  .meta({ id: 'CatalogGitSource', description: 'Where the plugin source lives.' })

// Why regex then refine: the regex is the published `pattern`; the refine adds length and
// reserved-name rules without reporting a bad key twice.
const QUALIFIED_PLUGIN_KEY_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*\.[a-z0-9]+(?:-[a-z0-9]+)*$/

export const marketplaceEntryFields = {
  /** Canonical `<publisher>.<id>` install identity; the manifest must carry the same `id`. */
  id: z
    .string()
    .regex(QUALIFIED_PLUGIN_KEY_RE, 'invalid qualified plugin key')
    .refine(
      (key) => !QUALIFIED_PLUGIN_KEY_RE.test(key) || isQualifiedPluginKey(key),
      'invalid qualified plugin key'
    )
    .meta(
      pluginFieldDoc(
        "`<publisher>.<id>`: the publisher is the repository owner, lowercased (Orca installs under this key, whatever the manifest's deprecated `publisher` says), and the id is the manifest's `id`. Each half is at most 64 characters, and the reserved names `constructor` and `prototype` are refused.",
        NEXT,
        ['acme.gleam-syntax']
      )
    ),
  source: pluginMarketplaceGitSourceSchema,
  description: safePluginDisplayText(z.string().min(1).max(4_096))
    .optional()
    .meta(pluginFieldDoc('Listing text shown in the marketplace.', NEXT)),
  categories: z
    .array(marketplaceCategorySchema)
    .max(PLUGIN_MARKETPLACE_CATEGORY_LIMIT)
    .default([])
    .meta({
      ...pluginFieldDoc('Lowercase slugs used to filter the marketplace, each listed once.', NEXT, [
        ['themes']
      ]),
      uniqueItems: true
    })
}

function rejectDuplicateCategories(
  entry: { categories: string[] },
  context: z.RefinementCtx
): void {
  const seen = new Set<string>()
  for (const [index, category] of entry.categories.entries()) {
    if (seen.has(category)) {
      context.addIssue({
        code: z.ZodIssueCode.custom,
        path: ['categories', index],
        message: `duplicate category: ${category}`
      })
    }
    seen.add(category)
  }
}

function rejectDuplicatePluginIds(
  marketplace: { plugins: { id: string }[] },
  context: z.RefinementCtx
): void {
  const seen = new Set<string>()
  for (const [index, plugin] of marketplace.plugins.entries()) {
    if (seen.has(plugin.id)) {
      context.addIssue({
        code: z.ZodIssueCode.custom,
        path: ['plugins', index, 'id'],
        message: `duplicate plugin id: ${plugin.id}`
      })
    }
    seen.add(plugin.id)
  }
}

export const pluginMarketplaceEntrySchema = z
  .strictObject(marketplaceEntryFields)
  .superRefine(rejectDuplicateCategories)

/** Normalized entry held in memory and in the snapshot cache, from either catalog file. */
const pluginMarketplaceListingEntrySchema = z
  .strictObject({
    ...marketplaceEntryFields,
    source: z.strictObject(catalogGitSourceFields),
    releases: z.array(pluginCatalogReleaseSchema).min(1).optional()
  })
  .superRefine(rejectDuplicateCategories)

export const marketplaceHeaderFields = {
  name: safePluginDisplayText(z.string().min(1).max(256)).meta(
    pluginFieldDoc('Catalog display name.', NEXT, ['Orca Plugins'])
  ),
  owner: marketplaceOwnerSchema.meta(
    pluginFieldDoc('Account that publishes the catalog.', NEXT, ['stablyai'])
  )
}

export const pluginMarketplaceSchema = z
  .strictObject({
    ...marketplaceHeaderFields,
    plugins: z.array(pluginMarketplaceEntrySchema).max(PLUGIN_MARKETPLACE_ENTRY_LIMIT)
  })
  .superRefine(rejectDuplicatePluginIds)

export const pluginMarketplaceListingSchema = z
  .strictObject({
    ...marketplaceHeaderFields,
    plugins: z.array(pluginMarketplaceListingEntrySchema).max(PLUGIN_MARKETPLACE_ENTRY_LIMIT)
  })
  .superRefine(rejectDuplicatePluginIds)

/** Host-derived trust metadata. Marketplace JSON cannot self-award either bit. */
export const pluginMarketplaceTrustMetadataSchema = z
  .strictObject({
    official: z.boolean(),
    bundled: z.boolean()
  })
  .refine((metadata) => !metadata.bundled || metadata.official, {
    message: 'bundled plugins must be official',
    path: ['bundled']
  })

export type PluginMarketplace = z.infer<typeof pluginMarketplaceListingSchema>
export type PluginMarketplaceEntry = z.infer<typeof pluginMarketplaceListingEntrySchema>
export type PluginMarketplaceGitSource = z.infer<typeof pluginMarketplaceGitSourceSchema>
export type PluginCatalogGitSource = z.infer<typeof catalogV2GitSourceSchema>

export const OFFICIAL_MARKETPLACE_GIT_SOURCE: PluginMarketplaceGitSource = {
  kind: 'git',
  url: 'https://github.com/stablyai/orca-plugins.git',
  ref: 'main'
}

export function splitQualifiedPluginKey(pluginKey: string): {
  publisher: string
  id: string
} | null {
  if (!isQualifiedPluginKey(pluginKey)) {
    return null
  }
  const separator = pluginKey.indexOf('.')
  return {
    publisher: pluginKey.slice(0, separator),
    id: pluginKey.slice(separator + 1)
  }
}

export function isReservedPluginIdentity(pluginKey: string): boolean {
  const identity = splitQualifiedPluginKey(pluginKey)
  return (
    identity !== null &&
    (isReservedPluginPublisher(identity.publisher) ||
      identity.id.startsWith(OFFICIAL_PLUGIN_ID_PREFIX))
  )
}

/** Orca's own publisher; reserved, so only the official catalog and bundled content carry it. */
export function hasOfficialPluginPublisher(pluginKey: string): boolean {
  return splitQualifiedPluginKey(pluginKey)?.publisher === OFFICIAL_PLUGIN_PUBLISHER
}

type GitRepositoryIdentity = {
  host: string
  owner: string
  repository: string
  /** Every path segment, so a GitLab subgroup move is a different repository. */
  path: string
}

// Why only these: a self-hosted server may serve `team/Plugin` and `team/plugin` as two repositories.
const CASE_INSENSITIVE_GIT_HOSTS = new Set(['github.com', 'gitlab.com', 'bitbucket.org'])

/** Extracts the host and first owner segment from the HTTPS/SSH Git forms the
 * installer accepts. It is intentionally only a provenance parser. */
export function parseGitRepositoryIdentity(url: string): GitRepositoryIdentity | null {
  const trimmed = url.trim()
  const scp = /^[^\s@/:]+@([^\s:]+):(.+)$/.exec(trimmed)
  if (scp) {
    return repositoryIdentity(scp[1]!, scp[2]!)
  }
  try {
    const parsed = new URL(trimmed)
    if (parsed.protocol !== 'https:' && parsed.protocol !== 'ssh:') {
      return null
    }
    return repositoryIdentity(parsed.hostname, parsed.pathname)
  } catch {
    return null
  }
}

function repositoryIdentity(host: string, repositoryPath: string): GitRepositoryIdentity | null {
  const segments = repositoryPath
    .replace(/^\/+|\/+$/g, '')
    .split('/')
    .filter(Boolean)
  // Why: the scp form is not normalized, so `stablyai/../evil` would read as the official owner.
  if (segments.length < 2 || segments.includes('..')) {
    return null
  }
  const repository = segments.at(-1)!.replace(/\.git$/i, '')
  if (!repository) {
    return null
  }
  const lowerHost = host.toLowerCase()
  const exactPath = [...segments.slice(0, -1), repository].join('/')
  const path = CASE_INSENSITIVE_GIT_HOSTS.has(lowerHost) ? exactPath.toLowerCase() : exactPath
  return { host: lowerHost, owner: segments[0]!, repository, path }
}

/** `host/owner` of a repository, with every GitLab subgroup (`gitlab.com/acme/tools`). */
export function gitRepositoryOwnerLabel(url: string): string | null {
  const identity = parseGitRepositoryIdentity(url)
  return identity
    ? [identity.host, ...identity.path.split('/').slice(0, -1)].join('/').toLowerCase()
    : null
}

/** Same repository regardless of URL spelling (https vs scp, `.git`, case where the host ignores it). */
export function isSameGitRepository(left: string, right: string): boolean {
  const a = parseGitRepositoryIdentity(left)
  const b = parseGitRepositoryIdentity(right)
  if (!a || !b) {
    return left.trim() === right.trim()
  }
  return a.host === b.host && a.path === b.path
}

/** Same plugin location: one repository and one directory in it; a moved directory is a move. */
export function isSamePluginSource(
  left: { url: string; path?: string },
  right: { url: string; path?: string }
): boolean {
  return isSameGitRepository(left.url, right.url) && (left.path ?? '') === (right.path ?? '')
}

/** Display form of a plugin location, naming the directory when it is not the repository root. */
export function pluginSourceLabel(source: { url: string; path?: string }): string {
  return source.path ? `${source.url} (${source.path})` : source.url
}

export function isOfficialOrganizationGitSource(url: string): boolean {
  const source = parseGitRepositoryIdentity(url)
  return source?.host === 'github.com' && source.owner.toLowerCase() === OFFICIAL_PLUGIN_PUBLISHER
}

export function isOfficialMarketplaceGitSource(url: string): boolean {
  const source = parseGitRepositoryIdentity(url)
  return (
    source?.host === 'github.com' &&
    source.owner.toLowerCase() === OFFICIAL_MARKETPLACE_OWNER &&
    source.repository.toLowerCase() === OFFICIAL_MARKETPLACE_REPOSITORY
  )
}