@jetci/ir

Build and discovery layer for JETCI workflows.

@jetci/ir finds workflow files, performs a discovery build using @jetci/runtime-shim, validates registrations, and then emits the final workflow bundle. It provides the baseline server/build capabilities and a host descriptor model for providers.

Baseline Usage

import {build} from "@jetci/ir"

const registrations = await build({
  workflowDir: ".jetci",
  outfile: "./dist/workflows.js",
})

By default this supports the baseline JETCI SDK events and runners, including push and the built-in runsOn values.

Provider Wrappers

Providers should create a wrapper package, such as @jetci/github-ir, that calls build() with a host extension. The provider wrapper supplies the provider SDK package name, additional event schemas, and runner option schemas.

import {build, eventListenerSchema} from "@jetci/ir"
import {z} from "zod"

export function buildGitHubCi(options: {
  workflowDir: string
  outfile: string
}) {
  return build({
    ...options,
    host: {
      sdkPackage: "@jetci/github-sdk",
      allowedRegistrationPackages: ["@jetci/github-sdk"],
      events: {
        "github.pull_request": eventListenerSchema(z.object({
          branches: z.array(z.string()).min(1),
          actions: z.array(z.enum(["opened", "synchronize", "closed"])).optional(),
        })),
      },
      jobOptions: z.object({
        runsOn: z.enum(["ubuntu-latest", "ubuntu-24.04-arm", "self-hosted"]),
      }),
    },
  })
}

Provider SDKs are bundled during discovery so their event definitions can be redirected to the generic runtime shim. Provider SDKs are externalized in the final workflow bundle by default.

Secrets

eventListenerSchema(paramsSchema) validates the shared listener envelope, including secrets. Discovery returns each listener's declared secret names so the host can resolve them before invoking the final bundle's live handler.

Secrets are host/orchestrator metadata only. IR serializes the names, never the values.

SDK Import Security

During discovery, only root .ci.ts files in the configured workflow directory get the active host.sdkPackage public API. Trusted provider SDK internals may use @jetci/sdk/extend to create scoped events/jobs. Other bundled dependencies that import protected SDK packages are routed to isolated runtime-shim islands, so their registrations can exist but are not read by IR.

Each registration carries origin.sdkPackage. allowedRegistrationPackages defaults to [host.sdkPackage], and IR validates discovery output against that allow-list. The final generated bundle also filters live registrars to the same allowed origins.

Registrar Access

SDKs expose live registrations through a stable ./registrar subpath. Discovery and runtime deliberately use different registrars:

• Discovery entrypoint imports @jetci/runtime-shim/registrar and exports serialized EVENT_REGISTRAR / JOB_REGISTRAR metadata for IR validation.
• Final bundle entrypoint imports workflows normally, then re-exports live EVENT_REGISTRAR / JOB_REGISTRAR from ${host.sdkPackage}/registrar so the caller can invoke registered event handlers and jobs.

The final bundle externalizes the baseline SDK and host.sdkPackage by default; otherwise workflow imports and the generated registrar export can end up with separate registrar copies. The esbuild security plugin rejects workflow-authored registrar imports, so only the generated entrypoint can touch those paths.

A host that owns the final entrypoint/runtime boundary may set host.includeBaseSdkInBundle: true to bundle the baseline JETCI SDK instead of externalizing it. This only removes the baseline SDK from IR's default externals; provider SDKs remain externalized unless the host configures its bundle behavior separately.

Public Helpers

• build(options): discover registrations and emit the final workflow bundle.
• JETCI_HOST_DESCRIPTOR: baseline host descriptor.
• mergeHostDescriptor(extension): merges provider host extensions with the baseline descriptor.
• eventListenerSchema(paramsSchema): validates the shared event listener envelope with provider-specific params.
• BASE_EVENT_LISTENER: base event registration shape.

Build

pnpm --dir packages/ir build