@cat-factory/server 0.6.0

package/dist/github/GitHubAppAuth.js

@@ -0,0 +1,95 @@
+import { base64url, pkcs8PemToDer } from '../crypto/encoding.js';
+// GitHub App authentication, implemented entirely on Web Crypto (`crypto.subtle`)
+// so it runs in a plain Workers isolate without Node `crypto` — and identically
+// under Node, where `crypto.subtle` is a global too:
+//   - the *app JWT* (RS256) authenticates as the App itself, used to mint tokens
+//     and read installation metadata;
+//   - *installation tokens* (short-lived, ~1h) authenticate as a specific
+//     installation for repo reads/writes, cached in the installation row.
+//
+// The signing key is imported once and reused. Tokens are treated as expired a
+// few minutes early to avoid using one that lapses mid-request; a cache miss is
+// harmless since a fresh token is cheaply minted from the app JWT.
+const TOKEN_SKEW_MS = 5 * 60 * 1000;
+const USER_AGENT = 'cat-factory';
+const API_VERSION = '2022-11-28';
+/**
+ * Installation tokens (live ~1h repo read/write credentials) are cached IN
+ * MEMORY, per isolate/process — never persisted. Persisting them put a plaintext
+ * credential at rest (readable from any DB dump / console / SQLi elsewhere); an
+ * in-memory cache keeps the hit rate high for a warm process while the token never
+ * outlives it. A cache miss just re-mints cheaply from the app JWT. The
+ * module-level map intentionally persists across requests within the same process.
+ */
+const tokenCache = new Map();
+export class GitHubAppAuth {
+    deps;
+    keyPromise;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** A short-lived RS256 JWT authenticating as the App. */
+    async appJwt() {
+        const key = await this.importKey();
+        const nowSec = Math.floor(this.deps.clock.now() / 1000);
+        const header = { alg: 'RS256', typ: 'JWT' };
+        // `iat` is backdated 60s to tolerate clock skew; GitHub caps `exp` at 10min.
+        const payload = { iat: nowSec - 60, exp: nowSec + 9 * 60, iss: this.deps.appId };
+        const signingInput = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(payload))}`;
+        const signature = await crypto.subtle.sign({ name: 'RSASSA-PKCS1-v1_5' }, key, new TextEncoder().encode(signingInput));
+        return `${signingInput}.${base64url(signature)}`;
+    }
+    /** A valid installation access token, minting + caching one if needed. */
+    async installationToken(installationId) {
+        return (await this.cachedToken(installationId)).token;
+    }
+    /**
+     * The permissions the installation token actually carries (App ∩ what the
+     * install approved) — the source of truth for capability checks. Comes free
+     * with the mint response and is cached alongside the token, so a warm process
+     * answers without a network call. Used by the provisioner to guard privileged
+     * actions (e.g. repo creation) before attempting them.
+     */
+    async installationPermissions(installationId) {
+        return (await this.cachedToken(installationId)).permissions;
+    }
+    async cachedToken(installationId) {
+        const cached = tokenCache.get(installationId);
+        if (cached && cached.expiresAt - TOKEN_SKEW_MS > this.deps.clock.now()) {
+            return cached;
+        }
+        return this.mintInstallationToken(installationId);
+    }
+    async mintInstallationToken(installationId) {
+        const jwt = await this.appJwt();
+        const res = await fetch(`${this.deps.apiBase}/app/installations/${installationId}/access_tokens`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${jwt}`,
+                accept: 'application/vnd.github+json',
+                'user-agent': USER_AGENT,
+                'x-github-api-version': API_VERSION,
+            },
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to mint installation token for ${installationId} (HTTP ${res.status})`);
+        }
+        const body = (await res.json());
+        const expiresAt = Date.parse(body.expires_at);
+        const entry = {
+            token: body.token,
+            permissions: body.permissions ?? {},
+            expiresAt: Number.isNaN(expiresAt) ? this.deps.clock.now() + 30 * 60 * 1000 : expiresAt,
+        };
+        // In-memory only (see tokenCache note) — never persisted.
+        tokenCache.set(installationId, entry);
+        return entry;
+    }
+    importKey() {
+        if (!this.keyPromise) {
+            this.keyPromise = crypto.subtle.importKey('pkcs8', pkcs8PemToDer(this.deps.privateKeyPem), { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign']);
+        }
+        return this.keyPromise;
+    }
+}
+//# sourceMappingURL=GitHubAppAuth.js.map

package/dist/github/GitHubAppAuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubAppAuth.js","sourceRoot":"","sources":["../../src/github/GitHubAppAuth.ts"],"names":[],"mappings":"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"}

package/dist/github/GitHubAppRegistry.d.ts

@@ -0,0 +1,57 @@
+import type { GitHubInstallation, GitHubInstallationRepository, InstallationPermissions } from '@cat-factory/kernel';
+import type { GitHubAppAuth } from './GitHubAppAuth.js';
+/** One configured App: its id and the auth that signs/mint for it. */
+export interface RegisteredApp {
+    appId: string;
+    auth: GitHubAppAuth;
+}
+/**
+ * The narrow token-minting surface {@link FetchGitHubClient} needs, so the client can
+ * be driven by something OTHER than the App registry — e.g. a static-PAT source in
+ * local mode. {@link GitHubAppRegistry} satisfies it structurally; a PAT source
+ * implements `installationToken` to return the token and may throw on the app-JWT
+ * paths (which only the installation discovery/listing calls use).
+ */
+export interface AppTokenSource {
+    /** The default App id used for app-JWT calls that don't name one. */
+    readonly defaultAppId: string;
+    /** Every configured App, iterated for cross-App installation discovery. */
+    apps(): readonly {
+        appId: string;
+    }[];
+    /** The auth (app-JWT signer) for an appId. */
+    authForApp(appId: string | null | undefined): {
+        appJwt(): Promise<string>;
+    };
+    /** An installation token (the repo-call credential). */
+    installationToken(installationId: number): Promise<string>;
+}
+export interface GitHubAppRegistryDependencies {
+    /** The default (restricted) App — always present; owns legacy installations. */
+    default: RegisteredApp;
+    /** The privileged App, when configured. */
+    privileged?: RegisteredApp;
+    /** Resolves an installation's owning appId from its persisted binding. */
+    installationRepository: GitHubInstallationRepository;
+}
+export declare class GitHubAppRegistry {
+    private readonly deps;
+    constructor(deps: GitHubAppRegistryDependencies);
+    get defaultAppId(): string;
+    /** Every configured App, for cross-App discovery (connect probe, listing). */
+    apps(): RegisteredApp[];
+    /** The auth for an appId, falling back to the default App for null/legacy/unknown ids. */
+    authForApp(appId: string | null | undefined): GitHubAppAuth;
+    /** An installation token, minted by the App that owns the installation. */
+    installationToken(installationId: number): Promise<string>;
+    /** The installation's granted permissions, via its owning App. */
+    installationPermissions(installationId: number): Promise<InstallationPermissions>;
+    /**
+     * Whether this installation's owning App can create repos — i.e. it's the
+     * privileged tier (ADR 0005). A null appId means the default App, which never
+     * can. Used to flag `canCreateRepos` on the connection.
+     */
+    canCreateRepos(installation: GitHubInstallation): boolean;
+    private ownerAuth;
+}
+//# sourceMappingURL=GitHubAppRegistry.d.ts.map

package/dist/github/GitHubAppRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubAppRegistry.d.ts","sourceRoot":"","sources":["../../src/github/GitHubAppRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,4BAA4B,EAC5B,uBAAuB,EACxB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAevD,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,aAAa,CAAA;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,2EAA2E;IAC3E,IAAI,IAAI,SAAS;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IACpC,8CAA8C;IAC9C,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG;QAAE,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,CAAA;IAC3E,wDAAwD;IACxD,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAC3D;AAED,MAAM,WAAW,6BAA6B;IAC5C,gFAAgF;IAChF,OAAO,EAAE,aAAa,CAAA;IACtB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,aAAa,CAAA;IAC1B,0EAA0E;IAC1E,sBAAsB,EAAE,4BAA4B,CAAA;CACrD;AAOD,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,6BAA6B,EAAI;IAEpE,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,8EAA8E;IAC9E,IAAI,IAAI,aAAa,EAAE,CAEtB;IAED,0FAA0F;IAC1F,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,CAK1D;IAED,2EAA2E;IACrE,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE/D;IAED,kEAAkE;IAC5D,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAEtF;IAED;;;;OAIG;IACH,cAAc,CAAC,YAAY,EAAE,kBAAkB,GAAG,OAAO,CAGxD;YAEa,SAAS;CASxB"}

package/dist/github/GitHubAppRegistry.js

@@ -0,0 +1,51 @@
+// installationId → owning appId. The mapping is immutable on GitHub (an
+// installation belongs to one App forever), so caching per-process is safe and
+// spares a read on the hot token-mint path.
+const ownerAppCache = new Map();
+export class GitHubAppRegistry {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get defaultAppId() {
+        return this.deps.default.appId;
+    }
+    /** Every configured App, for cross-App discovery (connect probe, listing). */
+    apps() {
+        return this.deps.privileged ? [this.deps.default, this.deps.privileged] : [this.deps.default];
+    }
+    /** The auth for an appId, falling back to the default App for null/legacy/unknown ids. */
+    authForApp(appId) {
+        if (appId && this.deps.privileged && appId === this.deps.privileged.appId) {
+            return this.deps.privileged.auth;
+        }
+        return this.deps.default.auth;
+    }
+    /** An installation token, minted by the App that owns the installation. */
+    async installationToken(installationId) {
+        return (await this.ownerAuth(installationId)).installationToken(installationId);
+    }
+    /** The installation's granted permissions, via its owning App. */
+    async installationPermissions(installationId) {
+        return (await this.ownerAuth(installationId)).installationPermissions(installationId);
+    }
+    /**
+     * Whether this installation's owning App can create repos — i.e. it's the
+     * privileged tier (ADR 0005). A null appId means the default App, which never
+     * can. Used to flag `canCreateRepos` on the connection.
+     */
+    canCreateRepos(installation) {
+        const owner = installation.appId ?? this.defaultAppId;
+        return this.deps.privileged !== undefined && owner === this.deps.privileged.appId;
+    }
+    async ownerAuth(installationId) {
+        let appId = ownerAppCache.get(installationId);
+        if (appId === undefined) {
+            const record = await this.deps.installationRepository.getByInstallationId(installationId);
+            appId = record?.appId ?? this.defaultAppId;
+            ownerAppCache.set(installationId, appId);
+        }
+        return this.authForApp(appId);
+    }
+}
+//# sourceMappingURL=GitHubAppRegistry.js.map

package/dist/github/GitHubAppRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubAppRegistry.js","sourceRoot":"","sources":["../../src/github/GitHubAppRegistry.ts"],"names":[],"mappings":"AAqDA,wEAAwE;AACxE,+EAA+E;AAC/E,4CAA4C;AAC5C,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAA;AAE/C,MAAM,OAAO,iBAAiB;IACC,IAAI;IAAjC,YAA6B,IAAmC;oBAAnC,IAAI;IAAkC,CAAC;IAEpE,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAA;IAChC,CAAC;IAED,8EAA8E;IAC9E,IAAI;QACF,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAC/F,CAAC;IAED,0FAA0F;IAC1F,UAAU,CAAC,KAAgC;QACzC,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,KAAK,KAAK,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YAC1E,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAA;QAClC,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAA;IAC/B,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,iBAAiB,CAAC,cAAsB;QAC5C,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAA;IACjF,CAAC;IAED,kEAAkE;IAClE,KAAK,CAAC,uBAAuB,CAAC,cAAsB;QAClD,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,uBAAuB,CAAC,cAAc,CAAC,CAAA;IACvF,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,YAAgC;QAC7C,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,CAAA;QACrD,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAA;IACnF,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,cAAsB;QAC5C,IAAI,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;QAC7C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,sBAAsB,CAAC,mBAAmB,CAAC,cAAc,CAAC,CAAA;YACzF,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,IAAI,CAAC,YAAY,CAAA;YAC1C,aAAa,CAAC,GAAG,CAAC,cAAc,EAAE,KAAK,CAAC,CAAA;QAC1C,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;IAC/B,CAAC;CACF"}

package/dist/github/GitHubCiStatusProvider.d.ts

@@ -0,0 +1,21 @@
+import type { BlockRepository, CiStatusProvider, CiStatusReport, GitHubClient } from '@cat-factory/kernel';
+import type { ResolveRepoTarget } from '../agents/ContainerAgentExecutor.js';
+export interface GitHubCiStatusProviderDependencies {
+    githubClient: GitHubClient;
+    /** Resolves the repo (installation + owner/name) a block's work targets. */
+    resolveRepoTarget: ResolveRepoTarget;
+    /** Reads the block's recorded PR ref (head branch). */
+    blockRepository: BlockRepository;
+}
+/**
+ * Reads a block's CI status from GitHub for the `ci` gate: resolve the PR head
+ * branch → its head commit (latest commit on the branch) → the check runs for
+ * that commit. Returns `{ headSha: null, checks: [] }` when there is no resolvable
+ * PR branch yet (the engine treats that as "nothing to gate").
+ */
+export declare class GitHubCiStatusProvider implements CiStatusProvider {
+    private readonly deps;
+    constructor(deps: GitHubCiStatusProviderDependencies);
+    getStatus(workspaceId: string, blockId: string): Promise<CiStatusReport>;
+}
+//# sourceMappingURL=GitHubCiStatusProvider.d.ts.map

package/dist/github/GitHubCiStatusProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubCiStatusProvider.d.ts","sourceRoot":"","sources":["../../src/github/GitHubCiStatusProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACb,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAA;AAE5E,MAAM,WAAW,kCAAkC;IACjD,YAAY,EAAE,YAAY,CAAA;IAC1B,4EAA4E;IAC5E,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,uDAAuD;IACvD,eAAe,EAAE,eAAe,CAAA;CACjC;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,kCAAkC,EAAI;IAEnE,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAyB7E;CACF"}

package/dist/github/GitHubCiStatusProvider.js

@@ -0,0 +1,39 @@
+/**
+ * Reads a block's CI status from GitHub for the `ci` gate: resolve the PR head
+ * branch → its head commit (latest commit on the branch) → the check runs for
+ * that commit. Returns `{ headSha: null, checks: [] }` when there is no resolvable
+ * PR branch yet (the engine treats that as "nothing to gate").
+ */
+export class GitHubCiStatusProvider {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async getStatus(workspaceId, blockId) {
+        const block = await this.deps.blockRepository.get(workspaceId, blockId);
+        const branch = block?.pullRequest?.branch;
+        if (!branch)
+            return { headSha: null, checks: [] };
+        const target = await this.deps.resolveRepoTarget(workspaceId, blockId);
+        if (!target)
+            return { headSha: null, checks: [] };
+        const ref = { owner: target.owner, repo: target.name };
+        // The head commit of the PR branch is the latest commit listed on that ref.
+        const commits = await this.deps.githubClient.listCommits(target.installationId, ref, {
+            sha: branch,
+        });
+        const headSha = commits.items[0]?.sha ?? null;
+        if (!headSha)
+            return { headSha: null, checks: [] };
+        const checks = await this.deps.githubClient.listCheckRuns(target.installationId, ref, headSha);
+        return {
+            headSha,
+            checks: checks.items.map((c) => ({
+                name: c.name,
+                status: c.status,
+                conclusion: c.conclusion,
+            })),
+        };
+    }
+}
+//# sourceMappingURL=GitHubCiStatusProvider.js.map

package/dist/github/GitHubCiStatusProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubCiStatusProvider.js","sourceRoot":"","sources":["../../src/github/GitHubCiStatusProvider.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,MAAM,OAAO,sBAAsB;IACJ,IAAI;IAAjC,YAA6B,IAAwC;oBAAxC,IAAI;IAAuC,CAAC;IAEzE,KAAK,CAAC,SAAS,CAAC,WAAmB,EAAE,OAAe;QAClD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QACvE,MAAM,MAAM,GAAG,KAAK,EAAE,WAAW,EAAE,MAAM,CAAA;QACzC,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;QAEjD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QACtE,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;QACjD,MAAM,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAA;QAEtD,4EAA4E;QAC5E,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,MAAM,CAAC,cAAc,EAAE,GAAG,EAAE;YACnF,GAAG,EAAE,MAAM;SACZ,CAAC,CAAA;QACF,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAA;QAC7C,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;QAElD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,cAAc,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;QAC9F,OAAO;YACL,OAAO;YACP,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC/B,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,UAAU,EAAE,CAAC,CAAC,UAAU;aACzB,CAAC,CAAC;SACJ,CAAA;IACH,CAAC;CACF"}

package/dist/github/GitHubMergeabilityProvider.d.ts

@@ -0,0 +1,26 @@
+import type { BlockRepository, GitHubClient, MergeabilityReport, MergeabilityVerdict, PullRequestMergeabilityProvider } from '@cat-factory/kernel';
+import type { ResolveRepoTarget } from '../agents/ContainerAgentExecutor.js';
+export interface GitHubMergeabilityProviderDependencies {
+    githubClient: GitHubClient;
+    /** Resolves the repo (installation + owner/name) a block's work targets. */
+    resolveRepoTarget: ResolveRepoTarget;
+    /** Reads the block's recorded PR ref (number). */
+    blockRepository: BlockRepository;
+}
+/**
+ * Reads a block's PR mergeability from GitHub for the `conflicts` gate. Returns
+ * `{ headSha: null, verdict: 'unknown' }` when there is no resolvable PR (the engine
+ * treats that as "nothing to gate"). Maps GitHub's lazily-computed `mergeable` /
+ * `mergeable_state` to the engine's small verdict: only `mergeable_state === 'dirty'`
+ * is a real conflict; a null/`unknown` reading means GitHub is still computing it
+ * (poll again); everything else (clean / behind / blocked / unstable) has no
+ * conflict to resolve.
+ */
+export declare class GitHubMergeabilityProvider implements PullRequestMergeabilityProvider {
+    private readonly deps;
+    constructor(deps: GitHubMergeabilityProviderDependencies);
+    getMergeability(workspaceId: string, blockId: string): Promise<MergeabilityReport>;
+}
+/** Map GitHub's `mergeable` / `mergeable_state` to the engine's mergeability verdict. */
+export declare function classifyMergeability(mergeable: boolean | null, mergeableState: string): MergeabilityVerdict;
+//# sourceMappingURL=GitHubMergeabilityProvider.d.ts.map

package/dist/github/GitHubMergeabilityProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubMergeabilityProvider.d.ts","sourceRoot":"","sources":["../../src/github/GitHubMergeabilityProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,+BAA+B,EAChC,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAA;AAE5E,MAAM,WAAW,sCAAsC;IACrD,YAAY,EAAE,YAAY,CAAA;IAC1B,4EAA4E;IAC5E,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,kDAAkD;IAClD,eAAe,EAAE,eAAe,CAAA;CACjC;AAED;;;;;;;;GAQG;AACH,qBAAa,0BAA2B,YAAW,+BAA+B;IACpE,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,sCAAsC,EAAI;IAEvE,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAevF;CACF;AAED,yFAAyF;AACzF,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,OAAO,GAAG,IAAI,EACzB,cAAc,EAAE,MAAM,GACrB,mBAAmB,CAOrB"}

package/dist/github/GitHubMergeabilityProvider.js

@@ -0,0 +1,38 @@
+/**
+ * Reads a block's PR mergeability from GitHub for the `conflicts` gate. Returns
+ * `{ headSha: null, verdict: 'unknown' }` when there is no resolvable PR (the engine
+ * treats that as "nothing to gate"). Maps GitHub's lazily-computed `mergeable` /
+ * `mergeable_state` to the engine's small verdict: only `mergeable_state === 'dirty'`
+ * is a real conflict; a null/`unknown` reading means GitHub is still computing it
+ * (poll again); everything else (clean / behind / blocked / unstable) has no
+ * conflict to resolve.
+ */
+export class GitHubMergeabilityProvider {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async getMergeability(workspaceId, blockId) {
+        const block = await this.deps.blockRepository.get(workspaceId, blockId);
+        const number = block?.pullRequest?.number;
+        if (number === undefined)
+            return { headSha: null, verdict: 'unknown' };
+        const target = await this.deps.resolveRepoTarget(workspaceId, blockId);
+        if (!target)
+            return { headSha: null, verdict: 'unknown' };
+        const { mergeable, mergeableState, headSha } = await this.deps.githubClient.getPullRequestMergeability(target.installationId, { owner: target.owner, repo: target.name }, number);
+        return { headSha, verdict: classifyMergeability(mergeable, mergeableState) };
+    }
+}
+/** Map GitHub's `mergeable` / `mergeable_state` to the engine's mergeability verdict. */
+export function classifyMergeability(mergeable, mergeableState) {
+    // 'dirty' is GitHub's signal that the PR conflicts with its base.
+    if (mergeableState === 'dirty')
+        return 'conflicted';
+    // Mergeability is computed asynchronously: null / 'unknown' means "not ready yet".
+    if (mergeable === null || mergeableState === 'unknown' || mergeableState === '')
+        return 'unknown';
+    // clean / behind / blocked / unstable / has_hooks: no merge conflict to resolve.
+    return 'mergeable';
+}
+//# sourceMappingURL=GitHubMergeabilityProvider.js.map

package/dist/github/GitHubMergeabilityProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubMergeabilityProvider.js","sourceRoot":"","sources":["../../src/github/GitHubMergeabilityProvider.ts"],"names":[],"mappings":"AAiBA;;;;;;;;GAQG;AACH,MAAM,OAAO,0BAA0B;IACR,IAAI;IAAjC,YAA6B,IAA4C;oBAA5C,IAAI;IAA2C,CAAC;IAE7E,KAAK,CAAC,eAAe,CAAC,WAAmB,EAAE,OAAe;QACxD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QACvE,MAAM,MAAM,GAAG,KAAK,EAAE,WAAW,EAAE,MAAM,CAAA;QACzC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAA;QAEtE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QACtE,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAA;QAEzD,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,GAC1C,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,0BAA0B,CACrD,MAAM,CAAC,cAAc,EACrB,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAC1C,MAAM,CACP,CAAA;QACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,CAAA;IAC9E,CAAC;CACF;AAED,yFAAyF;AACzF,MAAM,UAAU,oBAAoB,CAClC,SAAyB,EACzB,cAAsB;IAEtB,kEAAkE;IAClE,IAAI,cAAc,KAAK,OAAO;QAAE,OAAO,YAAY,CAAA;IACnD,mFAAmF;IACnF,IAAI,SAAS,KAAK,IAAI,IAAI,cAAc,KAAK,SAAS,IAAI,cAAc,KAAK,EAAE;QAAE,OAAO,SAAS,CAAA;IACjG,iFAAiF;IACjF,OAAO,WAAW,CAAA;AACpB,CAAC"}

package/dist/github/GitHubPullRequestMerger.d.ts

@@ -0,0 +1,23 @@
+import type { BlockRepository, GitHubClient, PullRequestMerger } from '@cat-factory/kernel';
+import type { ResolveRepoTarget } from '../agents/ContainerAgentExecutor.js';
+export interface GitHubPullRequestMergerDependencies {
+    githubClient: GitHubClient;
+    /** Resolves the repo (installation + owner/name) a block's work targets. */
+    resolveRepoTarget: ResolveRepoTarget;
+    /** Reads the block's recorded PR ref (number to merge). */
+    blockRepository: BlockRepository;
+}
+/**
+ * The single place a block's pull request is actually merged on GitHub. The
+ * execution engine calls this (via the {@link PullRequestMerger} port) before
+ * flipping a task to `done`, so `done` provably means "merged". Throws if the
+ * block has no PR number, the repo can't be resolved, or GitHub rejects the merge
+ * (failing required checks, conflicts) — the engine then leaves the block awaiting
+ * a manual merge / raises a review notification.
+ */
+export declare class GitHubPullRequestMerger implements PullRequestMerger {
+    private readonly deps;
+    constructor(deps: GitHubPullRequestMergerDependencies);
+    mergeForBlock(workspaceId: string, blockId: string): Promise<void>;
+}
+//# sourceMappingURL=GitHubPullRequestMerger.d.ts.map

package/dist/github/GitHubPullRequestMerger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubPullRequestMerger.d.ts","sourceRoot":"","sources":["../../src/github/GitHubPullRequestMerger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAC3F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAA;AAE5E,MAAM,WAAW,mCAAmC;IAClD,YAAY,EAAE,YAAY,CAAA;IAC1B,4EAA4E;IAC5E,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,2DAA2D;IAC3D,eAAe,EAAE,eAAe,CAAA;CACjC;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IACnD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,mCAAmC,EAAI;IAEpE,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BvE;CACF"}

package/dist/github/GitHubPullRequestMerger.js

@@ -0,0 +1,38 @@
+/**
+ * The single place a block's pull request is actually merged on GitHub. The
+ * execution engine calls this (via the {@link PullRequestMerger} port) before
+ * flipping a task to `done`, so `done` provably means "merged". Throws if the
+ * block has no PR number, the repo can't be resolved, or GitHub rejects the merge
+ * (failing required checks, conflicts) — the engine then leaves the block awaiting
+ * a manual merge / raises a review notification.
+ */
+export class GitHubPullRequestMerger {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async mergeForBlock(workspaceId, blockId) {
+        const target = await this.deps.resolveRepoTarget(workspaceId, blockId);
+        if (!target) {
+            throw new Error(`No GitHub repository resolved for block '${blockId}'; cannot merge.`);
+        }
+        const block = await this.deps.blockRepository.get(workspaceId, blockId);
+        const number = block?.pullRequest?.number;
+        if (number === undefined) {
+            throw new Error(`Block '${blockId}' has no pull-request number to merge.`);
+        }
+        await this.deps.githubClient.mergePullRequest(target.installationId, { owner: target.owner, repo: target.name }, number);
+        // Tear down the work branch now that it is merged. The branch is deterministic
+        // per task (`cat-factory/<blockId>`), so leaving it behind would let a later
+        // re-run of this block RESUME on already-merged commits — which a squash/rebase
+        // merge would re-introduce wholesale (those commits are not ancestors of base).
+        // Best-effort: a failed delete must never undo or fail the completed merge.
+        const branch = block?.pullRequest?.branch;
+        if (branch) {
+            await this.deps.githubClient
+                .deleteBranch(target.installationId, { owner: target.owner, repo: target.name }, branch)
+                .catch(() => { });
+        }
+    }
+}
+//# sourceMappingURL=GitHubPullRequestMerger.js.map

package/dist/github/GitHubPullRequestMerger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubPullRequestMerger.js","sourceRoot":"","sources":["../../src/github/GitHubPullRequestMerger.ts"],"names":[],"mappings":"AAWA;;;;;;;GAOG;AACH,MAAM,OAAO,uBAAuB;IACL,IAAI;IAAjC,YAA6B,IAAyC;oBAAzC,IAAI;IAAwC,CAAC;IAE1E,KAAK,CAAC,aAAa,CAAC,WAAmB,EAAE,OAAe;QACtD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QACtE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,4CAA4C,OAAO,kBAAkB,CAAC,CAAA;QACxF,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QACvE,MAAM,MAAM,GAAG,KAAK,EAAE,WAAW,EAAE,MAAM,CAAA;QACzC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,UAAU,OAAO,wCAAwC,CAAC,CAAA;QAC5E,CAAC;QACD,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAC3C,MAAM,CAAC,cAAc,EACrB,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAC1C,MAAM,CACP,CAAA;QAED,+EAA+E;QAC/E,6EAA6E;QAC7E,gFAAgF;QAChF,gFAAgF;QAChF,4EAA4E;QAC5E,MAAM,MAAM,GAAG,KAAK,EAAE,WAAW,EAAE,MAAM,CAAA;QACzC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY;iBACzB,YAAY,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC;iBACvF,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACpB,CAAC;IACH,CAAC;CACF"}

package/dist/github/WebCryptoWebhookVerifier.d.ts

@@ -0,0 +1,9 @@
+import type { WebhookVerifier } from '@cat-factory/kernel';
+export declare class WebCryptoWebhookVerifier implements WebhookVerifier {
+    private readonly secret;
+    private keyPromise?;
+    constructor(secret: string);
+    verify(rawBody: ArrayBuffer, signatureHeader: string | null): Promise<boolean>;
+    private importKey;
+}
+//# sourceMappingURL=WebCryptoWebhookVerifier.d.ts.map

package/dist/github/WebCryptoWebhookVerifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebCryptoWebhookVerifier.d.ts","sourceRoot":"","sources":["../../src/github/WebCryptoWebhookVerifier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAY1D,qBAAa,wBAAyB,YAAW,eAAe;IAGlD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,UAAU,CAAC,CAAoB;IAEvC,YAA6B,MAAM,EAAE,MAAM,EAAI;IAEzC,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnF;IAED,OAAO,CAAC,SAAS;CAYlB"}

package/dist/github/WebCryptoWebhookVerifier.js

@@ -0,0 +1,40 @@
+import { timingSafeEqual } from '../crypto/encoding.js';
+// Verifies GitHub webhook deliveries: GitHub signs the raw body with HMAC-SHA-256
+// using the App's webhook secret and sends `sha256=<hex>` in the
+// `X-Hub-Signature-256` header. We recompute the digest with Web Crypto
+// (`crypto.subtle`, a global on both workerd and Node 22+) and compare in constant
+// time, on the *raw* body bytes (verification must precede any JSON parse). Promoted
+// from the Worker infra so every facade verifies webhooks identically.
+const PREFIX = 'sha256=';
+export class WebCryptoWebhookVerifier {
+    secret;
+    keyPromise;
+    constructor(secret) {
+        this.secret = secret;
+    }
+    async verify(rawBody, signatureHeader) {
+        if (!signatureHeader || !signatureHeader.startsWith(PREFIX))
+            return false;
+        const provided = hexToBytes(signatureHeader.slice(PREFIX.length));
+        if (!provided)
+            return false;
+        const key = await this.importKey();
+        const computed = new Uint8Array(await crypto.subtle.sign('HMAC', key, rawBody));
+        return timingSafeEqual(provided, computed);
+    }
+    importKey() {
+        if (!this.keyPromise) {
+            this.keyPromise = crypto.subtle.importKey('raw', new TextEncoder().encode(this.secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+        }
+        return this.keyPromise;
+    }
+}
+function hexToBytes(hex) {
+    if (hex.length === 0 || hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex))
+        return null;
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++)
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return bytes;
+}
+//# sourceMappingURL=WebCryptoWebhookVerifier.js.map

package/dist/github/WebCryptoWebhookVerifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebCryptoWebhookVerifier.js","sourceRoot":"","sources":["../../src/github/WebCryptoWebhookVerifier.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,kFAAkF;AAClF,iEAAiE;AACjE,wEAAwE;AACxE,mFAAmF;AACnF,qFAAqF;AACrF,uEAAuE;AAEvE,MAAM,MAAM,GAAG,SAAS,CAAA;AAExB,MAAM,OAAO,wBAAwB;IAGN,MAAM;IAF3B,UAAU,CAAqB;IAEvC,YAA6B,MAAc;sBAAd,MAAM;IAAW,CAAC;IAE/C,KAAK,CAAC,MAAM,CAAC,OAAoB,EAAE,eAA8B;QAC/D,IAAI,CAAC,eAAe,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,KAAK,CAAA;QACzE,MAAM,QAAQ,GAAG,UAAU,CAAC,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;QACjE,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAA;QAE3B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAA;QAClC,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC,CAAA;QAC/E,OAAO,eAAe,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;IAC5C,CAAC;IAEO,SAAS;QACf,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CACvC,KAAK,EACL,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EACrC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAA;IACxB,CAAC;CACF;AAED,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACrF,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAC3F,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/github/ensureWorkBranch.d.ts

@@ -0,0 +1,26 @@
+export interface EnsureWorkBranchInput {
+    /** GitHub REST base, e.g. `https://api.github.com` (GitHub Enterprise overrides it). */
+    apiBase?: string;
+    /** A short-lived installation token authorised for the repo. */
+    token: string;
+    owner: string;
+    name: string;
+    /** The branch the work branch forks from (the repo's base). */
+    baseBranch: string;
+    /** The work branch to ensure, e.g. `cat-factory/<blockId>`. */
+    branch: string;
+    /**
+     * Whether to CREATE the work branch from base when it does not yet exist. Writers pass
+     * `true` (they need the branch); read-only agents pass `false` to PROBE only — they
+     * never write, so a missing branch means "nothing to read, use base", and creating it
+     * would only orphan an empty ref. Defaults to `true`.
+     */
+    create?: boolean;
+}
+/**
+ * Ensure `branch` is present on the remote. Writers (`create !== false`) create it from
+ * `baseBranch`'s tip when absent; read-only callers (`create: false`) only report whether
+ * it already exists. Returns whether the work branch is present afterwards.
+ */
+export declare function ensureWorkBranchViaRest(input: EnsureWorkBranchInput): Promise<boolean>;
+//# sourceMappingURL=ensureWorkBranch.d.ts.map

package/dist/github/ensureWorkBranch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureWorkBranch.d.ts","sourceRoot":"","sources":["../../src/github/ensureWorkBranch.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAmBD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,CA0D5F"}