@pipeline-builder/pipeline-data 4.3.10 → 4.3.12

package/lib/api/managed-toolchain.d.ts

@@ -0,0 +1,199 @@
+/**
+ * THE resolver for the managed toolchain (docs/plans/bootstrap-image-versioning.md
+ * §2). `pipeline-bootstrap@V` and `cdk-synth@V` are two SYSTEM-ORG plugin rows
+ * that share one release version `V`; every path that can resolve a managed
+ * name answers from here and nothing else may:
+ *
+ *   release pin given → that release, if it EXISTS (yanked / deprecated /
+ *                       never-promoted still resolve, with a warning; deleted ⇒ 404)
+ *   else org default  → the NEAREST `org_toolchain_default` walking caller → … → root
+ *   else canary       → the NEAREST `toolchain_rollout` membership, served only
+ *                       while it passes the scan + metadata guards
+ *   else platform     → `toolchain_platform_default`
+ *   else              → 409 TOOLCHAIN_NO_DEFAULT (never "highest version", D11)
+ *
+ * - Reads are ELEVATED (`runWithTenantContext({ isSuperAdmin: true })`, as
+ *   `versionReferences` does) and touch SYSTEM-ORG plugin rows only: the owner
+ *   rank of `pluginResolutionOrderBy` is never consulted, so a same-named row in
+ *   any other org is never a candidate.
+ * - Eligibility (D15) is a SET-time rule ({@link isEligibleRelease}); at resolve
+ *   time a pin / org default only has to exist.
+ * - Both halves always come from ONE release (`TOOLCHAIN_PAIR_MISMATCH` otherwise).
+ * - The answer carries `resolvedVia` and nothing about any other org: no
+ *   rollout membership, no ancestor's settings.
+ */
+import { AppError, ErrorCode, type GetParentOrgId, type ManagedToolchainPlugin, type PluginToolchain } from '@pipeline-builder/api-core';
+import type { CrudTx } from './crud-service.js';
+import type { ResolutionRefusal } from './plugin-resolution.js';
+import { type OrgToolchainDefault, type Plugin, type ToolchainRelease } from '../database/drizzle-schema.js';
+/** How a resolution chose its release. Never names the org it came from. */
+export type ToolchainResolvedVia = 'pin' | 'org-default' | 'canary' | 'default';
+/** A non-fatal note on a resolved release (synth prints it). */
+export interface ManagedToolchainWarning {
+    code: string;
+    message: string;
+    severity: 'info' | 'warning' | 'error';
+}
+/** One release, both halves. */
+export interface ManagedToolchainResolution {
+    releaseVersion: string;
+    resolvedVia: ToolchainResolvedVia;
+    bootstrap: Plugin;
+    synth: Plugin;
+    warnings: ManagedToolchainWarning[];
+}
+/** A resolver refusal: `code` is TOOLCHAIN_NO_DEFAULT, NOT_FOUND, TOOLCHAIN_PAIR_MISMATCH or VALIDATION_ERROR. */
+export declare class ManagedToolchainError extends AppError {
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown>);
+}
+/** The caller a resolution runs for. */
+export interface ManagedToolchainCaller {
+    orgId: string;
+}
+/** Whether `version` is a release version (`MAJOR.MINOR.PATCH`). */
+export declare function isToolchainReleaseVersion(version: unknown): version is string;
+/** What the resolver reads with: a drizzle transaction (or any drizzle database in tests). */
+export type ToolchainDb = Pick<CrudTx, 'select'>;
+/** How the resolver reads and walks the org tree (injectable for tests). */
+export interface ManagedToolchainDeps {
+    /** Run `fn` with ELEVATED reads. */
+    read<T>(fn: (db: ToolchainDb) => Promise<T>): Promise<T>;
+    /** An org's direct parent, or undefined for a root. Throws when it can't tell. */
+    getParent: GetParentOrgId;
+}
+/** Both halves of one release as stored, with the release row. */
+export interface ReleaseHalves {
+    releaseVersion: string;
+    release: ToolchainRelease | null;
+    bootstrap: Plugin | null;
+    synth: Plugin | null;
+}
+/** The release row and both SYSTEM-ORG halves of `releaseVersion` (deleted rows excluded). */
+export declare function loadReleaseHalves(db: ToolchainDb, releaseVersion: string): Promise<ReleaseHalves>;
+/**
+ * The caller's chain, own org first, lowercased: `[self, parent, …, root]`.
+ * The same parent walk as `org-reachability.ts` (platform's
+ * `GET /organization/:id/parent`), cycle-safe and capped at `MAX_ORG_DEPTH` like
+ * `reporting-retention.ts` — but FAIL-CLOSED: a lookup failure, a cycle or an
+ * over-deep chain throws rather than resolving the wrong org's toolchain.
+ */
+export declare function toolchainOrgChain(orgId: string, getParent: GetParentOrgId): Promise<string[]>;
+/** Test hook: drop cached parent lookups. */
+export declare function clearToolchainParentCacheForTests(): void;
+/** Test hook: replace the resolver's reads and hierarchy (null restores production). */
+export declare function setManagedToolchainDepsForTests(deps: ManagedToolchainDeps | null): void;
+/** Why a stored release is not LIVE (empty = live: both halves present, active, unyanked, not deprecated). */
+export type ReleaseLifecycleProblem = 'missing' | 'inactive' | 'yanked' | 'deprecated';
+/** Whether both halves are present (the release EXISTS). */
+export declare function releaseExists(h: ReleaseHalves): h is ReleaseHalves & {
+    bootstrap: Plugin;
+    synth: Plugin;
+};
+export declare function releaseLifecycleProblems(h: ReleaseHalves): ReleaseLifecycleProblem[];
+/**
+ * The bootstrap half's toolchain metadata (`pipelineManager`, `awsCdk`, …), or
+ * null when it carries no complete, valid one. Upload persists it on the row's
+ * `metadata` as flat `toolchain.<field>` keys (api-core `toolchainMetadata`).
+ */
+export declare function bootstrapToolchainOf(row: Plugin | null | undefined): PluginToolchain | null;
+/**
+ * The §8 candidate guards (pair, scan, metadata) a release fails, as their
+ * error codes — empty when it passes. The canary gate and concurrency are the
+ * platform-default service's; a canary is served only while this is empty.
+ */
+export declare function toolchainCandidateProblems(h: ReleaseHalves): ErrorCode[];
+/** {@link resolveManagedToolchain} with injected reads and hierarchy (tests). */
+export declare function resolveManagedToolchainWith(deps: ManagedToolchainDeps, caller: ManagedToolchainCaller, opts?: {
+    releasePin?: string;
+}): Promise<ManagedToolchainResolution>;
+/**
+ * Resolve the managed toolchain release for `caller` (see the module doc).
+ * Throws {@link ManagedToolchainError}: TOOLCHAIN_NO_DEFAULT (409, no platform
+ * default), NOT_FOUND (404, a missing / deleted pin), TOOLCHAIN_PAIR_MISMATCH
+ * (500), VALIDATION_ERROR (400, a malformed pin).
+ */
+export declare function resolveManagedToolchain(caller: ManagedToolchainCaller, opts?: {
+    releasePin?: string;
+}): Promise<ManagedToolchainResolution>;
+/** {@link isEligibleRelease} with injected reads and hierarchy (tests). */
+export declare function isEligibleReleaseWith(deps: ManagedToolchainDeps, orgId: string, releaseVersion: string): Promise<boolean>;
+/**
+ * D15: whether `orgId` may SET `releaseVersion` as a pipeline pin or its org
+ * default — both halves live (active, unyanked, not deprecated) AND either it
+ * has been the platform default or it is the caller's canary (nearest
+ * membership on its chain).
+ */
+export declare function isEligibleRelease(orgId: string, releaseVersion: string): Promise<boolean>;
+/**
+ * What the org-default panel shows a caller about ITS OWN org: never another
+ * org's choice, and of the ancestors only which one's default applies.
+ */
+export interface OrgToolchainOverview {
+    /** The caller's chain, own org first (lowercased). */
+    chain: string[];
+    /** What the org's UNPINNED pipelines resolve to now. */
+    effective: {
+        releaseVersion: string;
+        resolvedVia: ToolchainResolvedVia;
+        warnings: ManagedToolchainWarning[];
+    };
+    /** The caller org's own `org_toolchain_default` row, if it set one. */
+    ownDefault: OrgToolchainDefault | null;
+    /** The ancestor whose org default applies, when the org set none of its own. */
+    inheritedFrom: {
+        orgId: string;
+        releaseVersion: string;
+    } | null;
+    /** The caller's canary release (its NEAREST membership on the chain), or null. */
+    canaryRelease: string | null;
+    platformDefault: string | null;
+}
+/** {@link readOrgToolchainOverview} with injected reads and hierarchy (tests). */
+export declare function readOrgToolchainOverviewWith(deps: ManagedToolchainDeps, orgId: string): Promise<OrgToolchainOverview>;
+/**
+ * The caller org's toolchain overview (elevated reads, the same chain walk and
+ * precedence as {@link resolveManagedToolchain}). Throws what the resolver
+ * throws — TOOLCHAIN_NO_DEFAULT (409) when nothing resolves at all.
+ */
+export declare function readOrgToolchainOverview(orgId: string): Promise<OrgToolchainOverview>;
+/** One release the caller may pin or set (D15), with what the selectors show. */
+export interface EligibleToolchainRelease {
+    releaseVersion: string;
+    release: ToolchainRelease;
+    bootstrap: Plugin;
+    synth: Plugin;
+    /** THE platform default now. */
+    isPlatformDefault: boolean;
+    /** The caller's canary release (nearest membership). */
+    isCanary: boolean;
+}
+/** {@link listEligibleReleases} with injected reads and hierarchy (tests). */
+export declare function listEligibleReleasesWith(deps: ManagedToolchainDeps, orgId: string): Promise<{
+    platformDefault: string | null;
+    releases: EligibleToolchainRelease[];
+}>;
+/**
+ * Every release `orgId` may SET as a pipeline pin or its org default (D15, the
+ * same rule as {@link isEligibleRelease}), newest first. Never another org's
+ * data: a canary appears only when it is the caller's own (nearest) membership.
+ */
+export declare function listEligibleReleases(orgId: string): Promise<{
+    platformDefault: string | null;
+    releases: EligibleToolchainRelease[];
+}>;
+/** The resolver's error as the refusal shape step resolution reports (contract check, declared side, facts). */
+export declare function managedToolchainRefusal(err: ManagedToolchainError): ResolutionRefusal;
+/**
+ * Resolve ONE managed half for a step: the plugin row plus the resolution, or
+ * the refusal. Any non-resolver error (a database or hierarchy failure)
+ * propagates.
+ */
+export declare function resolveManagedToolchainHalf(caller: ManagedToolchainCaller, name: ManagedToolchainPlugin, opts?: {
+    releasePin?: string;
+}): Promise<{
+    plugin: Plugin;
+    resolution: ManagedToolchainResolution;
+} | {
+    refusal: ResolutionRefusal;
+    error: ManagedToolchainError;
+}>;