@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/providers/internal/normalizer.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Internal webhook normalizer for E2E tests.
+ *
+ * Implements the WebhookNormalizer interface from @kici-dev/engine for internal
+ * webhook sources. Used by the provider-agnostic E2E test suite to trigger the
+ * full webhook processing pipeline without GitHub dependencies.
+ *
+ * Verification is always skipped (internal sources use verification='none').
+ * Event type and routing key are extracted from custom headers.
+ */
+import type { WebhookNormalizer, SimulatedEvent, AccessCacheInvalidation } from '@kici-dev/engine';
+/**
+ * Internal provider implementation of WebhookNormalizer.
+ *
+ * Maps internal webhook headers and payloads to KiCI's universal SimulatedEvent format.
+ * Designed for E2E tests where payloads use normalized provider-agnostic structures
+ * (e.g., {ref: 'refs/heads/master', repository: {full_name: 'test/repo'}}).
+ */
+export declare class InternalWebhookNormalizer implements WebhookNormalizer {
+    readonly provider: "internal";
+    /**
+     * Extract routing key from internal webhook headers.
+     *
+     * Checks x-kici-routing-key first (explicit routing), then falls back
+     * to x-kici-source-id (generic source ID format).
+     */
+    extractRoutingKey(headers: Record<string, string>, _payload: unknown): string | null;
+    /**
+     * Extract delivery ID for deduplication.
+     *
+     * Checks x-delivery-id first, falls back to x-request-id.
+     */
+    extractDeliveryId(headers: Record<string, string>): string | null;
+    /**
+     * Extract event type from x-event-type header.
+     */
+    extractEventType(headers: Record<string, string>): string | null;
+    /**
+     * Verify signature -- always returns true.
+     *
+     * Internal sources use verification='none'. Actual verification is not
+     * needed for E2E test infrastructure where both sender and receiver
+     * are controlled by the test harness.
+     */
+    verifySignature(_body: string, _headers: Record<string, string>, _secret: string): boolean;
+    /**
+     * Extract repository identifier from an internal webhook payload.
+     *
+     * Internal events mimic GitHub-shaped payloads in E2E tests,
+     * so we extract from payload.repository.full_name if present.
+     */
+    extractRepoIdentifier(payload: unknown): string | null;
+    /**
+     * Extract ref from an internal webhook payload.
+     *
+     * Internal events use GitHub-shaped payloads, so extraction logic
+     * mirrors GitHub's: push -> payload.after, PR -> payload.pull_request.head.sha.
+     */
+    extractRef(eventType: string, payload: unknown): string;
+    /**
+     * Extract credentials -- internal sources carry no provider credentials.
+     */
+    extractCredentials(_payload: unknown): Record<string, unknown>;
+    /**
+     * Normalize an internal webhook event into a SimulatedEvent.
+     *
+     * Extracts branch information from payload.ref (stripping refs/heads/ prefix)
+     * and preserves the raw payload for trigger matching. Falls back to '__internal__'
+     * when no ref is present.
+     */
+    normalizeEvent(eventType: string, _action: string | null, payload: unknown): SimulatedEvent | null;
+    /**
+     * Map membership-related internal webhook events to ContributorCache
+     * invalidations.
+     *
+     * Internal E2E payloads are GitHub-shaped by design, so the mapping
+     * mirrors the GitHub normalizer exactly:
+     *
+     * - `member`: repo-user
+     * - `organization`: user-in-org
+     * - `membership`: user-in-org
+     * - `team` (repo-scoped actions only): repo
+     *
+     * This lets Bucket C E2E tests exercise the invalidation path through
+     * `sendInternalWebhook()` without requiring a real GitHub App.
+     */
+    getAccessCacheInvalidations(eventType: string, _action: string | null, payload: unknown): AccessCacheInvalidation[];
+}
+//# sourceMappingURL=normalizer.d.ts.map

package/dist/providers/internal/repo-url-builder.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Internal repo URL builder for E2E tests.
+ *
+ * Implements the RepoUrlBuilder interface from @kici-dev/engine by returning
+ * file:// URLs for local filesystem access, or network URLs (git://, http://)
+ * when a cloneUrlBase is configured for remote agent support.
+ */
+import type { RepoUrlBuilder } from '@kici-dev/engine';
+/**
+ * Internal provider implementation of RepoUrlBuilder.
+ *
+ * Builds clone URLs for repository access. When cloneUrlBase is set (e.g. to
+ * a git:// daemon URL), uses it for clone URLs so remote agents on different
+ * machines can clone. Otherwise falls back to file:// URLs for local access.
+ */
+export declare class InternalRepoUrlBuilder implements RepoUrlBuilder {
+    private readonly repoBasePath;
+    private readonly cloneUrlBase?;
+    readonly provider: "internal";
+    /**
+     * @param repoBasePath - Base directory where test repos live on disk
+     * @param cloneUrlBase - Optional URL base for clone operations (e.g. git://host/path).
+     *   When set, overrides the default file:// URL construction.
+     */
+    constructor(repoBasePath: string, cloneUrlBase?: string | undefined);
+    /**
+     * Build a clone URL for a repo.
+     *
+     * If cloneUrlBase is set, uses it directly (for remote agents).
+     * If repoIdentifier already starts with 'file://', returns it as-is.
+     * Otherwise, prepends 'file://' and the repoBasePath.
+     */
+    buildCloneUrl(repoIdentifier: string): string;
+    /**
+     * Build a raw file URL -- returns empty string.
+     *
+     * Internal repos have no web UI, so raw file URLs are not applicable.
+     * The lock file is fetched via InternalLockFileFetcher (filesystem) instead.
+     */
+    buildRawFileUrl(_repoIdentifier: string, _ref: string, _path: string): string;
+}
+//# sourceMappingURL=repo-url-builder.d.ts.map

package/dist/providers/universal-git/changed-files.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Universal-git changed-files fetcher.
+ *
+ * Implements the `ChangedFilesFetcher` interface from `@kici-dev/engine` for
+ * universal-git sources. Unlike the GitHub fetcher, this implementation does
+ * not make REST API calls — every supported forge (Forgejo, Gitea, Gogs,
+ * GitLab repo webhook, plain GitHub repo webhook) already includes the full
+ * `commits[].{added,modified,removed}` arrays in the push payload, so we
+ * extract them via JSONPath from the already-delivered webhook body.
+ *
+ * For PR events we return an empty list: the upstream trigger matcher treats
+ * empty changed-files as "match any path", which is the safest default when
+ * we don't have per-PR diff data. A follow-up can add an optional REST
+ * fetcher if source authors want PR path filtering.
+ */
+import type { ChangedFilesFetcher } from '@kici-dev/engine';
+import { type UniversalGitConfig } from './config.js';
+/**
+ * Universal-git implementation of ChangedFilesFetcher.
+ *
+ * One instance per universal-git source, configured with the source's
+ * expanded `payloadPaths` + `eventMapping`.
+ */
+export declare class UniversalGitChangedFilesFetcher implements ChangedFilesFetcher {
+    readonly provider: "generic";
+    private readonly paths;
+    private readonly eventMapping;
+    constructor(params: {
+        config: UniversalGitConfig;
+    });
+    /**
+     * Extract changed files from the webhook payload.
+     *
+     * @param _repoIdentifier Unused — all data is in `payload`.
+     * @param eventType       Raw header event type (pre-mapping).
+     * @param payload         The webhook body the forge delivered.
+     * @param _credentials    Unused — no REST call is made.
+     */
+    getChangedFiles(_repoIdentifier: string, eventType: string, payload: unknown, _credentials: unknown): Promise<string[]>;
+    private classifyEvent;
+}
+//# sourceMappingURL=changed-files.d.ts.map

package/dist/providers/universal-git/clone-token.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Universal-git clone-token provider.
+ *
+ * Implements the `CloneTokenProvider` interface from `@kici-dev/engine` for
+ * universal-git sources. Unlike GitHub — which mints a fresh installation
+ * token via JWT — universal-git auth is entirely static: the customer stores
+ * a long-lived PAT / Basic-auth password / SSH private key in the
+ * orchestrator's secret store, and we resolve + return it verbatim at
+ * dispatch time.
+ *
+ * The value returned here is the raw secret material:
+ *   - `credentialType === 'pat' | 'basic'`: the PAT / password string
+ *   - `credentialType === 'ssh'`: the PEM-encoded private key (the agent
+ *     materializes it to a tempfile and wires `GIT_SSH_COMMAND` — see
+ *     Phase 4 dispatch protocol + agent work)
+ *
+ * The token's "kind" (basic vs ssh) is NOT carried through this interface;
+ * it is propagated via `QueuedJobInput.gitAuth` in Phase 4. For Phase 2 we
+ * expose a richer `issueGitAuth()` method on this class that the dispatcher
+ * can call directly once Phase 4 adds `sourceAuth`/`workflowAuth` to the
+ * dispatch schema.
+ */
+import type { CloneTokenProvider, ProviderGitAuth } from '@kici-dev/engine';
+import type { SecretResolver } from '../../secrets/secret-resolver.js';
+import type { UniversalGitConfig } from './config.js';
+/**
+ * Structured auth material the agent needs to clone a universal-git repo.
+ *
+ * Phase 4: serialized into the new `sourceAuth` / `workflowAuth` fields on
+ * `jobDispatchSchema`. The shape matches `ProviderGitAuth` from
+ * `@kici-dev/engine` with additional SSH fields pulled from the source
+ * config (`sshHostKeyPolicy`, `sshKnownHostsPem`).
+ */
+export interface UniversalGitAuth extends ProviderGitAuth {
+    kind: 'basic' | 'ssh';
+}
+/**
+ * Universal-git implementation of CloneTokenProvider.
+ *
+ * Bound to a single source (orgId + sourceId + config). The orchestrator
+ * constructs one per registered universal-git source.
+ */
+export declare class UniversalGitCloneTokenProvider implements CloneTokenProvider {
+    private readonly params;
+    readonly provider: "generic";
+    constructor(params: {
+        orgId: string;
+        sourceId: string;
+        config: UniversalGitConfig;
+        secretResolver: SecretResolver;
+    });
+    /**
+     * Create a clone token — the raw secret material (PAT / password / SSH key).
+     *
+     * The orchestrator dispatch pipeline currently threads this string into
+     * `jobDispatch.token`, which the agent uses as HTTPS Basic-auth password
+     * via `http.extraHeader`. SSH support requires the Phase 4 dispatch-schema
+     * split (sourceAuth.kind = 'ssh') — which is where the agent gains the
+     * ability to materialize the PEM key and wire `GIT_SSH_COMMAND`.
+     *
+     * @returns The resolved secret string, or `null` when the secret is
+     * missing (source misconfigured — caller treats this as a clone failure).
+     */
+    createCloneToken(_repoIdentifier: string, _credentials: unknown): Promise<string | null>;
+    /**
+     * Richer variant that returns the full `UniversalGitAuth` shape instead
+     * of just the secret string. The Phase 4 dispatcher calls this via the
+     * `CloneTokenProvider.issueGitAuth?` interface hook so the agent
+     * receives the auth `kind` + `user` + SSH host-key policy alongside the
+     * secret.
+     *
+     * The method signature matches `CloneTokenProvider.issueGitAuth?` but
+     * universal-git ignores the inbound `repoIdentifier` / `credentials`
+     * args — the secret lives under a per-source scope (`__source__/<id>`)
+     * and is bound to the source at construction time, not to the inbound
+     * webhook.
+     */
+    issueGitAuth(_repoIdentifier?: string, _credentials?: unknown, opts?: {
+        runId?: string;
+        jobId?: string;
+    }): Promise<UniversalGitAuth | null>;
+}
+//# sourceMappingURL=clone-token.d.ts.map

package/dist/providers/universal-git/config.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Zod schema + preset table for universal-git source configuration.
+ *
+ * A universal-git source is a `generic_webhook_sources` row with a non-null
+ * `git_config` column. The config carries everything the orchestrator needs
+ * to build clone URLs, fetch lock files, parse changed files, and issue
+ * clone credentials against a user-supplied git server (Forgejo / Gitea /
+ * Gogs / GitLab repo-webhook / plain GitHub repo-webhook).
+ *
+ * Presets expand into full `payloadPaths` for each supported forge; custom
+ * (preset-less) configs spell out the paths explicitly. Adding a new forge
+ * means adding a row to `UNIVERSAL_GIT_PRESETS` — no new migration, no
+ * provider code changes.
+ */
+import { z } from 'zod';
+/**
+ * Preset identifier. Picks a canonical payload-path bundle for a forge whose
+ * webhook shape is close enough to GitHub's that JSONPath extraction works
+ * verbatim.
+ */
+export declare const UniversalGitPreset: z.ZodEnum<{
+    custom: "custom";
+    forgejo: "forgejo";
+    gitea: "gitea";
+    gogs: "gogs";
+    "gitlab-repo": "gitlab-repo";
+    "github-repo": "github-repo";
+}>;
+export type UniversalGitPreset = z.infer<typeof UniversalGitPreset>;
+/**
+ * Credential type for the git clone step. `pat` and `basic` both use HTTPS
+ * Basic auth (PAT is Basic auth with user=`x-access-token` or user=`oauth2`
+ * depending on forge); `ssh` uses an SSH key + `GIT_SSH_COMMAND`.
+ */
+export declare const UniversalGitCredentialType: z.ZodEnum<{
+    basic: "basic";
+    pat: "pat";
+    ssh: "ssh";
+}>;
+export type UniversalGitCredentialType = z.infer<typeof UniversalGitCredentialType>;
+/**
+ * SSH host-key verification policy. `accept-new` auto-trusts the forge on
+ * first connection (safe default for private ops but logs a one-time
+ * warning). `pinned` requires `sshKnownHostsPem` and refuses any host key
+ * that doesn't match — use for production-grade supply-chain hardening.
+ */
+export declare const SshHostKeyPolicy: z.ZodEnum<{
+    "accept-new": "accept-new";
+    pinned: "pinned";
+}>;
+export type SshHostKeyPolicy = z.infer<typeof SshHostKeyPolicy>;
+/**
+ * Reference to a secret in the orchestrator's secret store. Resolved at
+ * dispatch time via `SecretResolver.resolveNamed()`. The secret itself lives
+ * at scope `__source__/<sourceId>`, key = `credentialRef.key`, optionally
+ * in a specific backend via `credentialRef.store` (defaults to `pg`).
+ */
+export declare const CredentialRefSchema: z.ZodObject<{
+    key: z.ZodString;
+    store: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CredentialRef = z.infer<typeof CredentialRefSchema>;
+/**
+ * Payload extraction paths (JSONPath). Each preset supplies canonical values;
+ * `custom` requires all fields to be set explicitly.
+ */
+export declare const UniversalGitPayloadPathsSchema: z.ZodObject<{
+    repoIdentifier: z.ZodString;
+    pushRef: z.ZodString;
+    pushSha: z.ZodString;
+    defaultBranch: z.ZodString;
+    commitsAdded: z.ZodString;
+    commitsModified: z.ZodString;
+    commitsRemoved: z.ZodString;
+}, z.core.$strip>;
+export type UniversalGitPayloadPaths = z.infer<typeof UniversalGitPayloadPathsSchema>;
+/**
+ * Header-to-event-name mapping. Most forges send an `X-Event-Type`-style
+ * header; a few send different names for the same semantic event (e.g.
+ * Gogs sends `push` while GitLab sends `Push Hook`). The universal-git
+ * normalizer uses this map to collapse forge-specific values into the
+ * kici-internal `push` / `pull_request` / ... event names.
+ */
+export declare const EventMappingSchema: z.ZodObject<{
+    push: z.ZodArray<z.ZodString>;
+    pullRequest: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type EventMapping = z.infer<typeof EventMappingSchema>;
+/**
+ * Complete universal-git configuration stored in `generic_webhook_sources.git_config`.
+ *
+ * Validation refinements (enforced by Zod):
+ *   - `credentialType === 'ssh'` implies `credentialUser` is unused (ignored).
+ *   - `sshHostKeyPolicy === 'pinned'` requires `sshKnownHostsPem`.
+ *   - `preset === 'custom'` requires explicit `payloadPaths` and `eventMapping`.
+ *   - Non-custom presets ignore caller-supplied `payloadPaths` / `eventMapping`
+ *     in favour of the preset defaults (see `expandUniversalGitConfig`).
+ */
+export declare const UniversalGitConfigSchema: z.ZodObject<{
+    preset: z.ZodEnum<{
+        custom: "custom";
+        forgejo: "forgejo";
+        gitea: "gitea";
+        gogs: "gogs";
+        "gitlab-repo": "gitlab-repo";
+        "github-repo": "github-repo";
+    }>;
+    gitUrlTemplate: z.ZodString;
+    credentialRef: z.ZodObject<{
+        key: z.ZodString;
+        store: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    credentialType: z.ZodEnum<{
+        basic: "basic";
+        pat: "pat";
+        ssh: "ssh";
+    }>;
+    credentialUser: z.ZodOptional<z.ZodString>;
+    sshHostKeyPolicy: z.ZodDefault<z.ZodEnum<{
+        "accept-new": "accept-new";
+        pinned: "pinned";
+    }>>;
+    sshKnownHostsPem: z.ZodOptional<z.ZodString>;
+    payloadPaths: z.ZodOptional<z.ZodObject<{
+        repoIdentifier: z.ZodString;
+        pushRef: z.ZodString;
+        pushSha: z.ZodString;
+        defaultBranch: z.ZodString;
+        commitsAdded: z.ZodString;
+        commitsModified: z.ZodString;
+        commitsRemoved: z.ZodString;
+    }, z.core.$strip>>;
+    eventMapping: z.ZodOptional<z.ZodObject<{
+        push: z.ZodArray<z.ZodString>;
+        pullRequest: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type UniversalGitConfig = z.infer<typeof UniversalGitConfigSchema>;
+/**
+ * Canonical preset definitions. Expanded into full `payloadPaths` +
+ * `eventMapping` by `expandUniversalGitConfig`. Every forge in this table
+ * emits push / PR payloads that are structurally identical to GitHub's at
+ * the fields we care about (repository.full_name, commits[].added, etc.).
+ *
+ * `webhookEventHeader` is the HTTP header each forge sets on outbound
+ * webhook deliveries to communicate the event type. It is consumed by the
+ * generic webhook ingester (`generic_webhook_sources.event_type_header`) to
+ * classify the event before passing it to the universal-git normalizer. The
+ * source manager auto-populates the row's `event_type_header` from this
+ * field when an operator picks a preset and does not override the header
+ * explicitly.
+ */
+export declare const UNIVERSAL_GIT_PRESETS: Record<Exclude<UniversalGitPreset, 'custom'>, {
+    payloadPaths: UniversalGitPayloadPaths;
+    eventMapping: EventMapping;
+    webhookEventHeader: string;
+}>;
+/**
+ * Resolve the canonical webhook event-type header for a preset. Returns
+ * `null` when the preset is `custom` (operator must supply the header
+ * explicitly via `eventTypeHeader`).
+ */
+export declare function presetWebhookEventHeader(preset: UniversalGitPreset): string | null;
+/**
+ * Expand a validated `UniversalGitConfig` into a form where `payloadPaths`
+ * and `eventMapping` are always populated. Non-custom presets pull from
+ * `UNIVERSAL_GIT_PRESETS`; `custom` passes through the caller-supplied
+ * values (Zod has already enforced that both are present).
+ */
+export declare function expandUniversalGitConfig(config: UniversalGitConfig): UniversalGitConfig & {
+    payloadPaths: UniversalGitPayloadPaths;
+    eventMapping: EventMapping;
+};
+/**
+ * Parse a raw value (e.g. `git_config` JSONB from the DB) into a validated
+ * `UniversalGitConfig`. Returns `null` when the input is null/undefined;
+ * throws a ZodError on any other invalid shape.
+ */
+export declare function parseUniversalGitConfig(raw: unknown): UniversalGitConfig | null;
+/**
+ * Safe-parse variant. Returns `{ ok: true, config }` on success, or
+ * `{ ok: false, error }` on validation failure. Null/undefined inputs
+ * produce `{ ok: true, config: null }`.
+ */
+export declare function safeParseUniversalGitConfig(raw: unknown): {
+    ok: true;
+    config: UniversalGitConfig | null;
+} | {
+    ok: false;
+    error: z.ZodError;
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/providers/universal-git/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Universal-git provider bundle factory + barrel re-exports.
+ *
+ * A universal-git source is a `generic_webhook_sources` row with a non-null
+ * `git_config` column. At startup (and on config reload) the orchestrator
+ * walks every such row and calls `createUniversalGitProviderBundle()` to
+ * register a ProviderBundle under the source's routing key.
+ *
+ * Classes:
+ *   - `UniversalGitWebhookNormalizer` — normalizes push/PR payloads for any
+ *     forge whose webhook body is declared via JSONPath (`payloadPaths`).
+ *   - `UniversalGitLockFileFetcher` — shallow-clones the repo, sparse on
+ *     `.kici/`, reads `kici.lock.json` (5 MiB cap, 30 s budget).
+ *   - `UniversalGitChangedFilesFetcher` — extracts `commits[]` diffs via
+ *     JSONPath; no REST call.
+ *   - `UniversalGitCloneTokenProvider` — resolves the source-scoped secret
+ *     and returns the raw PAT/Basic/SSH material.
+ *   - `UniversalGitRepoUrlBuilder` — substitutes `{owner}`/`{name}`/`{repo}`
+ *     in the source's `gitUrlTemplate`.
+ *
+ * No `ContributorResolver` or `CheckStatusPoster` is wired for v1 — forge
+ * API support for those is uneven and adding it is a separate phase.
+ */
+import type { ProviderBundle } from '../../provider-registry.js';
+import type { GenericWebhookSource } from '../../db/types.js';
+import type { SecretResolver } from '../../secrets/secret-resolver.js';
+import { type UniversalGitConfig } from './config.js';
+export { UniversalGitWebhookNormalizer } from './normalizer.js';
+export { UniversalGitLockFileFetcher, LockFileTooLargeError } from './lock-file.js';
+export { UniversalGitChangedFilesFetcher } from './changed-files.js';
+export { UniversalGitCloneTokenProvider, type UniversalGitAuth } from './clone-token.js';
+export { UniversalGitRepoUrlBuilder, splitRepoIdentifier } from './repo-url.js';
+export { prepareSshAuth, prepareSshAuthSync, composeGitSshCommand, type SshAuthArtefacts, type SshAuthArtefactsSync, type PrepareSshAuthOptions, } from './ssh-auth.js';
+export { UniversalGitConfigSchema, parseUniversalGitConfig, safeParseUniversalGitConfig, expandUniversalGitConfig, presetWebhookEventHeader, UNIVERSAL_GIT_PRESETS, type UniversalGitConfig, type UniversalGitPreset, type UniversalGitCredentialType, type CredentialRef, } from './config.js';
+/**
+ * Normalize a `generic_webhook_sources` row's `git_config` into a parsed
+ * `UniversalGitConfig`. The column is `ColumnType<string | Record<...> |
+ * null, ...>` so it can arrive as either a JSON string (when the DB driver
+ * hasn't auto-parsed JSONB) or a plain object (when it has).
+ */
+export declare function parseSourceGitConfig(raw: string | Record<string, unknown> | null | undefined): UniversalGitConfig | null;
+/**
+ * Build a complete `ProviderBundle` for one universal-git source.
+ *
+ * The caller is responsible for invoking this at startup + config reload
+ * for every `generic_webhook_sources` row whose `git_config` is non-null,
+ * and for (un)registering the bundle against `providerRegistry` under the
+ * source's routing key (format: `generic:<orgId>:<sourceId>`).
+ *
+ * Returns `null` when the source has no `git_config` (i.e. it is a plain
+ * generic webhook, not a universal-git source) — callers can rely on this
+ * to differentiate the two shapes without re-parsing the row.
+ */
+export declare function createUniversalGitProviderBundle(source: Pick<GenericWebhookSource, 'id' | 'customer_id' | 'routing_key' | 'git_config'>, secretResolver: SecretResolver): ProviderBundle | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/universal-git/lock-file.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Universal-git lock file fetcher.
+ *
+ * Implements `LockFileFetcher` from `@kici-dev/engine` by shallow-cloning the
+ * source repo into a temporary directory, scoped to the `^\.kici/` path
+ * whitelist via git sparse-checkout. This keeps the payload tiny (tens of
+ * KiB for a normal workflows bundle) even when the repo itself is large.
+ *
+ * Safety caps (all enforced):
+ *   - **5 MiB max** for the cloned `.kici/kici.lock.json` file. Rejected
+ *     with `LockFileTooLargeError` when exceeded.
+ *   - **30 s timeout** on each git invocation. The wall-clock budget for
+ *     an entire fetch cycle (all git calls combined) is also 30 s.
+ *   - **Path whitelist `^\.kici/`.** Enforced by `sparse-checkout set
+ *     --cone .kici` so nothing outside that prefix ever hits disk.
+ *
+ * Auth:
+ *   - HTTPS Basic (PAT / basic-auth): injected via `git -c
+ *     http.extraHeader=Authorization: Basic <base64>` so the secret never
+ *     appears in the repo URL / logs.
+ *   - SSH: materialized via `prepareSshAuthSync()` and surfaced through
+ *     `GIT_SSH_COMMAND`; tempfiles are always cleaned up in a `finally`.
+ *
+ * This fetcher is used at two sites:
+ *   - Registration: when a default-branch push arrives for a universal-git
+ *     source, the processor calls `fetchLockFile(repoId, sha, credentials)`
+ *     to re-read the workflow manifest.
+ *   - Global-workflow dispatch: cross-provider globals resolve the lock
+ *     file via the registration's provider bundle.
+ */
+import type { LockFileFetcher, LockFile } from '@kici-dev/engine';
+import type { SecretResolver } from '../../secrets/secret-resolver.js';
+import type { UniversalGitConfig } from './config.js';
+/**
+ * Typed error for the 5 MiB cap. Callers can differentiate this from
+ * generic fetch failures for metrics / logging.
+ */
+export declare class LockFileTooLargeError extends Error {
+    readonly repoIdentifier: string;
+    readonly sizeBytes: number;
+    readonly limitBytes: number;
+    constructor(repoIdentifier: string, sizeBytes: number, limitBytes?: number);
+}
+/**
+ * Universal-git implementation of LockFileFetcher.
+ *
+ * Bound to a single source (orgId + sourceId + config). The orchestrator
+ * constructs one per registered universal-git source.
+ */
+export declare class UniversalGitLockFileFetcher implements LockFileFetcher {
+    private readonly params;
+    readonly provider: "generic";
+    private readonly repoUrlBuilder;
+    constructor(params: {
+        orgId: string;
+        sourceId: string;
+        config: UniversalGitConfig;
+        secretResolver: SecretResolver;
+    });
+    /**
+     * Shallow-clone the source repo at `ref` into a private tempdir, read
+     * `.kici/kici.lock.json`, and tear down.
+     *
+     * @returns The parsed `LockFile` on success, or `null` when the path
+     * doesn't exist in the repo (i.e. user hasn't added a lock file yet).
+     * Throws on any other failure — caller catches + emits
+     * `kici_universal_git_registration_errors_total{reason}`.
+     */
+    fetchLockFile(repoIdentifier: string, ref: string, _credentials: unknown): Promise<LockFile | null>;
+}
+//# sourceMappingURL=lock-file.d.ts.map

package/dist/providers/universal-git/normalizer.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Universal-git webhook normalizer.
+ *
+ * Implements the `WebhookNormalizer` interface from `@kici-dev/engine` for any
+ * forge that emits GitHub-shaped push / PR payloads. The structure of each
+ * forge's payload is declared via JSONPath expressions in the source's
+ * `git_config.payloadPaths`, so a single class covers Forgejo, Gitea, Gogs,
+ * GitLab repo webhooks, and plain-GitHub repo webhooks.
+ *
+ * Signatures are verified per source in the upstream generic-webhook
+ * verification path (HMAC-SHA256 / plain token / IP allow-list); this
+ * normalizer therefore short-circuits `verifySignature` and relies on the
+ * caller's pre-verification, same as `GenericWebhookNormalizer`.
+ */
+import type { WebhookNormalizer, SimulatedEvent } from '@kici-dev/engine';
+import { type UniversalGitConfig } from './config.js';
+/**
+ * Webhook normalizer for universal-git sources.
+ *
+ * Each instance is bound to one source's expanded config (preset-resolved
+ * `payloadPaths` + `eventMapping`). The orchestrator constructs one per
+ * registered `generic_webhook_sources` row with a non-null `git_config`.
+ */
+export declare class UniversalGitWebhookNormalizer implements WebhookNormalizer {
+    readonly provider: "generic";
+    private readonly routingKey;
+    private readonly paths;
+    private readonly eventMapping;
+    constructor(params: {
+        routingKey: string;
+        config: UniversalGitConfig;
+    });
+    /**
+     * Routing key is pre-assigned per source. The generic source-id header is
+     * still honoured for test compatibility, but the orchestrator pipeline
+     * already knows the routing key by the time this is invoked.
+     */
+    extractRoutingKey(headers: Record<string, string>, _payload: unknown): string | null;
+    /**
+     * Most universal-git forges send one of the following (in priority order).
+     * Returning null lets the pipeline fall back to request-level dedup.
+     */
+    extractDeliveryId(headers: Record<string, string>): string | null;
+    /**
+     * Event type header varies per forge. We accept all common spellings;
+     * `normalizeEvent` collapses the value back to KiCI's canonical names via
+     * the source's `eventMapping`.
+     */
+    extractEventType(headers: Record<string, string>): string | null;
+    /**
+     * Signature verification is performed by the generic webhook pipeline
+     * upstream; the normalizer only cooperates by returning `true`.
+     */
+    verifySignature(_body: string, _headers: Record<string, string>, _secret: string): boolean;
+    /**
+     * Normalize the forge payload into a `SimulatedEvent`. Uses JSONPath
+     * extraction for the repo identifier + ref + SHA so the same code works
+     * against every supported forge.
+     */
+    normalizeEvent(eventType: string, action: string | null, payload: unknown): SimulatedEvent | null;
+    /**
+     * Repo identifier via JSONPath. Returns `null` when the expression
+     * yields no match — callers treat this as "no repo context".
+     */
+    extractRepoIdentifier(payload: unknown): string | null;
+    /**
+     * Git ref / SHA extraction. For push, we resolve `pushSha`; for PR-shaped
+     * events, we fall back to `pull_request.head.sha` (or `object_attributes.last_commit.id`
+     * for GitLab). Unknown event types resolve to `HEAD` so the orchestrator
+     * can still evaluate triggers against the default branch.
+     */
+    extractRef(eventType: string, payload: unknown): string;
+    /**
+     * Universal-git sources carry no provider-native auth in the payload —
+     * the orchestrator resolves `credentialRef` out-of-band via the secret
+     * store. This method therefore returns an empty record.
+     */
+    extractCredentials(_payload: unknown): Record<string, unknown>;
+    /**
+     * Extension hook used by the processor's `isDefaultBranchPush` check so it
+     * does not need to hardcode `payload.repository.default_branch`. The
+     * engine interface does not yet declare this method; it is consumed via
+     * an optional chain (`normalizer.extractDefaultBranch?.(payload)`), so it
+     * is safe to ship ahead of the interface change in Phase 3.
+     */
+    extractDefaultBranch(payload: unknown): string | null;
+    /** Classify the raw event header against the source's eventMapping. */
+    private classifyEvent;
+}
+//# sourceMappingURL=normalizer.d.ts.map