@voltro/plugin-releases 0.0.0-stage → 0.83.0

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+import { Schema } from 'effect';
+
+export declare const releaseErrors: readonly [typeof ReleaseNotFound, typeof ReleaseRefused];
+
+export declare class ReleaseNotFound extends ReleaseNotFound_base {
+}
+
+declare const ReleaseNotFound_base: Schema.TaggedErrorClass<ReleaseNotFound, "ReleaseNotFound", {
+    readonly _tag: Schema.tag<"ReleaseNotFound">;
+} & {
+    app: typeof Schema.String;
+    version: Schema.optional<typeof Schema.String>;
+    channel: Schema.optional<typeof Schema.String>;
+}>;
+
+export declare class ReleaseRefused extends ReleaseRefused_base {
+}
+
+declare const ReleaseRefused_base: Schema.TaggedErrorClass<ReleaseRefused, "ReleaseRefused", {
+    readonly _tag: Schema.tag<"ReleaseRefused">;
+} & {
+    reason: typeof Schema.String;
+}>;
+
+export { }

package/dist/errors.js

@@ -0,0 +1,9 @@
+import { Schema as e } from "effect";
+//#region src/errors.ts
+var t = class extends e.TaggedError()("ReleaseNotFound", {
+	app: e.String,
+	version: e.optional(e.String),
+	channel: e.optional(e.String)
+}) {}, n = class extends e.TaggedError()("ReleaseRefused", { reason: e.String }) {}, r = [t, n];
+//#endregion
+export { t as ReleaseNotFound, n as ReleaseRefused, r as releaseErrors };

package/dist/index.d.ts

@@ -0,0 +1,445 @@
+import { ColumnBuilder } from '@voltro/database';
+import { FieldDefinitions } from '@voltro/database';
+import { InferRow } from '@voltro/database';
+import { Schema } from 'effect';
+import { Table } from '@voltro/database';
+import { VoltroPlugin } from '@voltro/protocol';
+
+export declare const BASE_NAME = "@voltro/plugin-releases";
+
+/** -1 / 0 / 1 like `Array.sort` wants. A pre-release sorts below its release. */
+export declare const compareVersions: (a: string, b: string) => number;
+
+/** What the running client should do, from the policy and its own version. */
+export declare const evaluatePolicy: (policy: ReleasePolicy, client: {
+    readonly version: string;
+    readonly installId: string;
+    readonly cohorts?: ReadonlyArray<string>;
+}) => PolicyVerdict;
+
+export declare type ExpoFeedAnswer = {
+    readonly kind: 'manifest';
+    readonly manifest: ExpoManifest;
+} | {
+    readonly kind: 'no-update';
+} | {
+    readonly kind: 'rollback';
+    readonly commitTime: string;
+};
+
+export declare interface ExpoManifest {
+    readonly id: string;
+    readonly createdAt: string;
+    readonly runtimeVersion: string;
+    readonly launchAsset: {
+        readonly hash: string;
+        readonly key: string;
+        readonly contentType: string;
+        readonly url: string;
+    };
+    readonly assets: ReadonlyArray<{
+        readonly hash: string;
+        readonly key: string;
+        readonly contentType: string;
+        readonly url: string;
+    }>;
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly extra: Readonly<Record<string, unknown>>;
+}
+
+export declare interface FeedArtifact {
+    readonly kind: string;
+    readonly target: string | null;
+    readonly url: string;
+    readonly sha256: string;
+    readonly size: number;
+    readonly signature: string | null;
+    readonly assetKey: string | null;
+    readonly contentType: string | null;
+}
+
+export declare interface FeedClient {
+    readonly installId: string;
+    readonly currentVersion: string | null;
+    readonly cohorts?: ReadonlyArray<string>;
+}
+
+export declare interface FeedRelease {
+    readonly id: string;
+    readonly version: string;
+    readonly buildId: string | null;
+    readonly notes: string | null;
+    readonly createdAt: Date;
+    readonly rolloutPercent: number;
+    readonly rolloutSalt: string;
+    readonly cohorts: ReadonlyArray<string> | null;
+    readonly artifacts: ReadonlyArray<FeedArtifact>;
+}
+
+/**
+ * Is this install inside the rollout? Monotonic in `percent`: an install that
+ * was in at 10 % is still in at 50 %, because the bucket does not move while
+ * the salt stands. A named cohort is always in.
+ */
+export declare const inRollout: (input: RolloutInput) => boolean;
+
+export declare const isNewerVersion: (candidate: string, current: string) => boolean;
+
+/** Is this release the one to hand this client? Newer than what it runs, and
+ *  the client is inside the rollout. */
+export declare const offeredTo: (release: FeedRelease, client: FeedClient) => boolean;
+
+/** `darwin-aarch64` from a user agent, best effort; null when unknown. */
+export declare const osFromUserAgent: (ua: string) => {
+    readonly os: string;
+    readonly arch?: string;
+} | null;
+
+/** Parse `1.4.0`, `1.4.0-beta.2`, `v2.0.1`; `null` when it is not a version. */
+export declare const parseVersion: (raw: string) => {
+    readonly parts: ReadonlyArray<number>;
+    readonly pre: ReadonlyArray<string>;
+} | null;
+
+/** Which artefact a download link should hand an OS/arch, or null. */
+export declare const pickDownload: (release: FeedRelease, os: string, arch?: string) => FeedArtifact | null;
+
+declare const PolicySchema: Schema.Struct<{
+    app: typeof Schema.String;
+    channel: typeof Schema.String;
+    latestVersion: Schema.NullOr<typeof Schema.String>;
+    minSupportedVersion: Schema.NullOr<typeof Schema.String>;
+    killSwitches: Schema.Record$<typeof Schema.String, Schema.Array$<typeof Schema.String>>;
+    rolloutPercent: typeof Schema.Number;
+    rolloutSalt: Schema.NullOr<typeof Schema.String>;
+    cohorts: Schema.NullOr<Schema.Array$<typeof Schema.String>>;
+}>;
+
+export declare interface PolicyVerdict {
+    /** The client must update before it may continue. */
+    readonly blocked: boolean;
+    /** A newer version exists on the channel — and this install is in its rollout. */
+    readonly updateAvailable: boolean;
+    readonly latestVersion: string | null;
+    /** Feature keys the running version must treat as off. */
+    readonly killed: ReadonlyArray<string>;
+}
+
+export declare type PolicyWire = typeof PolicySchema.Type;
+
+export declare const RELEASE_APPS_TABLE = "_voltro_release_apps";
+
+export declare const RELEASE_ARTIFACTS_TABLE = "_voltro_release_artifacts";
+
+export declare const RELEASE_CHANNELS_TABLE = "_voltro_release_channels";
+
+export declare const RELEASE_EVENTS_TABLE = "_voltro_release_events";
+
+export declare const RELEASE_PLATFORMS: readonly ["web", "ios", "android", "macos", "windows", "linux"];
+
+export declare const RELEASE_SHELLS: readonly ["pwa", "expo", "tauri", "electron"];
+
+export declare type ReleaseAppRow = InferRow<typeof releaseAppsTable>;
+
+export declare const releaseAppsTable: Table<"_voltro_release_apps", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    /** The app's name as the project spells it (`mobile`, `desktop`, `web`). */
+    readonly app: ColumnBuilder<string, "text", boolean>;
+    readonly platform: ColumnBuilder<string, "text", boolean>;
+    readonly shell: ColumnBuilder<string, "text", boolean>;
+    /** `com.acme.orders` — the store identity, where one exists. */
+    readonly bundleId: ColumnBuilder<string | null, "text", boolean>;
+    /** Public key the client verifies the feed with (minisign for Tauri,
+     *  the Expo code-signing certificate for expo-updates). */
+    readonly updaterPublicKey: ColumnBuilder<string | null, "text", boolean>;
+    /** Expo: the runtime version the OTA bundles target. */
+    readonly runtimeVersion: ColumnBuilder<string | null, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
+}>, true, "byReleaseAppTarget">;
+
+export declare interface ReleaseAppTarget {
+    /** `desktop`, `mobile`, `web` — the app as the project names it. */
+    readonly app: string;
+    readonly platform: 'web' | 'ios' | 'android' | 'macos' | 'windows' | 'linux';
+    readonly shell: 'pwa' | 'expo' | 'tauri' | 'electron';
+    readonly bundleId?: string;
+    readonly updaterPublicKey?: string;
+    readonly runtimeVersion?: string;
+    /** Channels to create at boot. Default `['stable', 'beta', 'internal']`. */
+    readonly channels?: ReadonlyArray<string>;
+}
+
+export declare type ReleaseArtifactRow = InferRow<typeof releaseArtifactsTable>;
+
+export declare const releaseArtifactsTable: Table<"_voltro_release_artifacts", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly releaseId: ColumnBuilder<string, "text", boolean>;
+    /** `dmg` | `msi` | `nsis` | `appimage` | `deb` | `rpm` | `ipa` | `aab` | `apk` | `expo-bundle` | `expo-asset` | `web-build`. */
+    readonly kind: ColumnBuilder<string, "text", boolean>;
+    /** Updater target: `darwin-aarch64`, `windows-x86_64`, `linux-x86_64`, `ios`, `android`. */
+    readonly target: ColumnBuilder<string | null, "text", boolean>;
+    /** Where the bytes are — a storage ref URL, a CDN URL. The feed hands this out. */
+    readonly url: ColumnBuilder<string, "text", boolean>;
+    readonly sha256: ColumnBuilder<string, "text", boolean>;
+    readonly size: ColumnBuilder<number, "integer", boolean>;
+    /** minisign / Expo code-signing signature over the bytes. */
+    readonly signature: ColumnBuilder<string | null, "text", boolean>;
+    readonly notarized: ColumnBuilder<boolean, "boolean", true>;
+    /** Expo: the asset's key/path inside the update. */
+    readonly assetKey: ColumnBuilder<string | null, "text", boolean>;
+    readonly contentType: ColumnBuilder<string | null, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
+}>, true, "byReleaseArtifactRelease">;
+
+export declare type ReleaseChannelRow = InferRow<typeof releaseChannelsTable>;
+
+export declare const releaseChannelsTable: Table<"_voltro_release_channels", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly appId: ColumnBuilder<string, "text", boolean>;
+    /** `stable`, `beta`, `internal`, … */
+    readonly name: ColumnBuilder<string, "text", boolean>;
+    readonly currentReleaseId: ColumnBuilder<string | null, "text", boolean>;
+    /** Below this version a client is blocked until it updates. */
+    readonly minSupportedVersion: ColumnBuilder<string | null, "text", boolean>;
+    /** Feature keys switched off for specific versions: `{ key: [versions] }`. */
+    readonly killSwitches: ColumnBuilder<unknown, "json", boolean>;
+    /** Public channel: downloads need no session. */
+    readonly public: ColumnBuilder<boolean, "boolean", true>;
+    /** Unsigned artefacts are refused unless this is set (internal only). */
+    readonly allowUnsigned: ColumnBuilder<boolean, "boolean", true>;
+    readonly updatedAt: ColumnBuilder<Date, "timestamp", true>;
+}>, true, "byReleaseChannelApp">;
+
+export declare type ReleaseEventRow = InferRow<typeof releaseEventsTable>;
+
+export declare const releaseEventsTable: Table<"_voltro_release_events", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly appId: ColumnBuilder<string, "text", boolean>;
+    readonly channelId: ColumnBuilder<string | null, "text", boolean>;
+    readonly releaseId: ColumnBuilder<string | null, "text", boolean>;
+    /** `promote` | `rollback` | `rollout` | `policy` | `create` | `upload`. */
+    readonly kind: ColumnBuilder<string, "text", boolean>;
+    readonly reason: ColumnBuilder<string | null, "text", boolean>;
+    readonly actorId: ColumnBuilder<string | null, "text", boolean>;
+    readonly detail: ColumnBuilder<unknown, "json", boolean>;
+    readonly at: ColumnBuilder<Date, "timestamp", true>;
+}>, true, "byReleaseEventApp">;
+
+export declare class ReleaseNotFound extends ReleaseNotFound_base {
+}
+
+declare const ReleaseNotFound_base: Schema.TaggedErrorClass<ReleaseNotFound, "ReleaseNotFound", {
+    readonly _tag: Schema.tag<"ReleaseNotFound">;
+} & {
+    app: typeof Schema.String;
+    version: Schema.optional<typeof Schema.String>;
+    channel: Schema.optional<typeof Schema.String>;
+}>;
+
+export declare type ReleasePlatform = (typeof RELEASE_PLATFORMS)[number];
+
+export declare interface ReleasePolicy {
+    readonly app: string;
+    readonly channel: string;
+    /** The channel's current release version, or null before the first promote. */
+    readonly latestVersion: string | null;
+    readonly minSupportedVersion: string | null;
+    /** `{ featureKey: [versions the feature is switched off for] }` */
+    readonly killSwitches: Readonly<Record<string, ReadonlyArray<string>>>;
+    readonly rolloutPercent: number;
+    readonly rolloutSalt: string | null;
+    readonly cohorts: ReadonlyArray<string> | null;
+}
+
+export declare class ReleaseRefused extends ReleaseRefused_base {
+}
+
+declare const ReleaseRefused_base: Schema.TaggedErrorClass<ReleaseRefused, "ReleaseRefused", {
+    readonly _tag: Schema.tag<"ReleaseRefused">;
+} & {
+    reason: typeof Schema.String;
+}>;
+
+export declare type ReleaseRow = InferRow<typeof releasesTable>;
+
+/** The scope that promotes, rolls out, rolls back and changes policy. */
+export declare const RELEASES_MANAGE_SCOPE = "releases:manage";
+
+export declare const RELEASES_TABLE = "_voltro_releases";
+
+export declare type ReleaseShell = (typeof RELEASE_SHELLS)[number];
+
+export declare const releasesPlugin: (options: ReleasesPluginOptions) => VoltroPlugin;
+
+export declare interface ReleasesPluginOptions {
+    /** The app targets this api releases for; created on activation if absent. */
+    readonly apps: ReadonlyArray<ReleaseAppTarget>;
+    /** Write-time compaction after every `create`; see `planRetention`. */
+    readonly retention?: ReleasesRetention;
+    /** HTTP prefix of the feeds. Default `/releases`. */
+    readonly prefix?: string;
+    readonly name?: string;
+    /** Testing seam. */
+    readonly now?: () => number;
+}
+
+export declare interface ReleasesRetention {
+    /** Releases kept per channel (newest by version), beyond whatever any channel
+     *  points to. Default 10; floors at 1. */
+    readonly keep?: number;
+    /** Per-channel override by channel name: `{ internal: 3 }`. */
+    readonly perChannel?: Readonly<Record<string, number>>;
+}
+
+export declare const releasesTable: Table<"_voltro_releases", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly appId: ColumnBuilder<string, "text", boolean>;
+    readonly channelId: ColumnBuilder<string, "text", boolean>;
+    readonly version: ColumnBuilder<string, "text", boolean>;
+    /** Build identity (the worker's build id, the OTA update id, the CI run). */
+    readonly buildId: ColumnBuilder<string | null, "text", boolean>;
+    /** Markdown release notes. */
+    readonly notes: ColumnBuilder<string | null, "text", boolean>;
+    readonly state: ColumnBuilder<string, "text", true>;
+    /** 0–100; 100 once complete. */
+    readonly rolloutPercent: ColumnBuilder<number, "integer", true>;
+    /** Salt for the deterministic cohort hash — fixed per release. */
+    readonly rolloutSalt: ColumnBuilder<string, "text", boolean>;
+    /** Named cohorts that always get the release (`tenant:acme`). */
+    readonly cohorts: ColumnBuilder<unknown, "json", boolean>;
+    readonly createdBy: ColumnBuilder<string | null, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
+    readonly updatedAt: ColumnBuilder<Date, "timestamp", true>;
+}>, true, "byReleaseAppChannel" | "byReleaseVersion">;
+
+export declare const releaseTables: readonly [ Table<"_voltro_release_apps", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    /** The app's name as the project spells it (`mobile`, `desktop`, `web`). */
+    readonly app: ColumnBuilder<string, "text", boolean>;
+    readonly platform: ColumnBuilder<string, "text", boolean>;
+    readonly shell: ColumnBuilder<string, "text", boolean>;
+    /** `com.acme.orders` — the store identity, where one exists. */
+    readonly bundleId: ColumnBuilder<string | null, "text", boolean>;
+    /** Public key the client verifies the feed with (minisign for Tauri,
+     *  the Expo code-signing certificate for expo-updates). */
+    readonly updaterPublicKey: ColumnBuilder<string | null, "text", boolean>;
+    /** Expo: the runtime version the OTA bundles target. */
+    readonly runtimeVersion: ColumnBuilder<string | null, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
+}>, true, "byReleaseAppTarget">, Table<"_voltro_release_channels", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly appId: ColumnBuilder<string, "text", boolean>;
+    /** `stable`, `beta`, `internal`, … */
+    readonly name: ColumnBuilder<string, "text", boolean>;
+    readonly currentReleaseId: ColumnBuilder<string | null, "text", boolean>;
+    /** Below this version a client is blocked until it updates. */
+    readonly minSupportedVersion: ColumnBuilder<string | null, "text", boolean>;
+    /** Feature keys switched off for specific versions: `{ key: [versions] }`. */
+    readonly killSwitches: ColumnBuilder<unknown, "json", boolean>;
+    /** Public channel: downloads need no session. */
+    readonly public: ColumnBuilder<boolean, "boolean", true>;
+    /** Unsigned artefacts are refused unless this is set (internal only). */
+    readonly allowUnsigned: ColumnBuilder<boolean, "boolean", true>;
+    readonly updatedAt: ColumnBuilder<Date, "timestamp", true>;
+}>, true, "byReleaseChannelApp">, Table<"_voltro_releases", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly appId: ColumnBuilder<string, "text", boolean>;
+    readonly channelId: ColumnBuilder<string, "text", boolean>;
+    readonly version: ColumnBuilder<string, "text", boolean>;
+    /** Build identity (the worker's build id, the OTA update id, the CI run). */
+    readonly buildId: ColumnBuilder<string | null, "text", boolean>;
+    /** Markdown release notes. */
+    readonly notes: ColumnBuilder<string | null, "text", boolean>;
+    readonly state: ColumnBuilder<string, "text", true>;
+    /** 0–100; 100 once complete. */
+    readonly rolloutPercent: ColumnBuilder<number, "integer", true>;
+    /** Salt for the deterministic cohort hash — fixed per release. */
+    readonly rolloutSalt: ColumnBuilder<string, "text", boolean>;
+    /** Named cohorts that always get the release (`tenant:acme`). */
+    readonly cohorts: ColumnBuilder<unknown, "json", boolean>;
+    readonly createdBy: ColumnBuilder<string | null, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
+    readonly updatedAt: ColumnBuilder<Date, "timestamp", true>;
+}>, true, "byReleaseAppChannel" | "byReleaseVersion">, Table<"_voltro_release_artifacts", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly releaseId: ColumnBuilder<string, "text", boolean>;
+    /** `dmg` | `msi` | `nsis` | `appimage` | `deb` | `rpm` | `ipa` | `aab` | `apk` | `expo-bundle` | `expo-asset` | `web-build`. */
+    readonly kind: ColumnBuilder<string, "text", boolean>;
+    /** Updater target: `darwin-aarch64`, `windows-x86_64`, `linux-x86_64`, `ios`, `android`. */
+    readonly target: ColumnBuilder<string | null, "text", boolean>;
+    /** Where the bytes are — a storage ref URL, a CDN URL. The feed hands this out. */
+    readonly url: ColumnBuilder<string, "text", boolean>;
+    readonly sha256: ColumnBuilder<string, "text", boolean>;
+    readonly size: ColumnBuilder<number, "integer", boolean>;
+    /** minisign / Expo code-signing signature over the bytes. */
+    readonly signature: ColumnBuilder<string | null, "text", boolean>;
+    readonly notarized: ColumnBuilder<boolean, "boolean", true>;
+    /** Expo: the asset's key/path inside the update. */
+    readonly assetKey: ColumnBuilder<string | null, "text", boolean>;
+    readonly contentType: ColumnBuilder<string | null, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
+}>, true, "byReleaseArtifactRelease">, Table<"_voltro_release_events", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly appId: ColumnBuilder<string, "text", boolean>;
+    readonly channelId: ColumnBuilder<string | null, "text", boolean>;
+    readonly releaseId: ColumnBuilder<string | null, "text", boolean>;
+    /** `promote` | `rollback` | `rollout` | `policy` | `create` | `upload`. */
+    readonly kind: ColumnBuilder<string, "text", boolean>;
+    readonly reason: ColumnBuilder<string | null, "text", boolean>;
+    readonly actorId: ColumnBuilder<string | null, "text", boolean>;
+    readonly detail: ColumnBuilder<unknown, "json", boolean>;
+    readonly at: ColumnBuilder<Date, "timestamp", true>;
+}>, true, "byReleaseEventApp">];
+
+/** The `latest*.yml` document. `sha512` is what electron-updater verifies; a
+ *  release uploaded with sha256 only carries it under `sha256` and the file
+ *  entry says so — the client refuses, which is the honest outcome. */
+export declare const renderElectronLatestYml: (release: FeedRelease, platform: "win" | "mac" | "linux", sha512ByArtifact?: Readonly<Record<string, string>>) => string | null;
+
+/**
+ * The expo-updates answer for a client (`expo-runtime-version`,
+ * `expo-current-update-id`). The launch asset is the `expo-bundle` artefact
+ * whose `target` is the client platform; every other `expo-asset` rides along.
+ */
+export declare const renderExpoFeed: (release: FeedRelease | null, client: FeedClient & {
+    readonly platform: "ios" | "android";
+    readonly runtimeVersion: string;
+    readonly currentUpdateId: string | null;
+}, channel: {
+    readonly runtimeVersion: string | null;
+    readonly rolledBackTo: {
+        readonly commitTime: Date;
+    } | null;
+}) => ExpoFeedAnswer;
+
+/** The Tauri updater document for one target, or null for "no update". */
+export declare const renderTauriFeed: (release: FeedRelease, client: FeedClient & {
+    readonly target: string;
+}) => TauriUpdaterResponse | null;
+
+/** The install's bucket, 0–99, stable for one salt. */
+export declare const rolloutBucket: (installId: string, salt: string) => number;
+
+export declare interface RolloutInput {
+    readonly installId: string;
+    readonly salt: string;
+    readonly percent: number;
+    /** The install's named cohorts (`tenant:acme`), matched against the release's. */
+    readonly installCohorts?: ReadonlyArray<string>;
+    readonly releaseCohorts?: ReadonlyArray<string> | null;
+}
+
+/** Sort versions descending. */
+export declare const sortVersionsDesc: (versions: ReadonlyArray<string>) => ReadonlyArray<string>;
+
+export declare interface TauriUpdaterResponse {
+    readonly version: string;
+    readonly notes: string;
+    readonly pub_date: string;
+    readonly platforms: Readonly<Record<string, {
+        readonly signature: string;
+        readonly url: string;
+    }>>;
+}
+
+export { }