@tahminator/pipeline 1.0.57 → 1.0.59-beta.2d7a142f

package/README.md

@@ -9,7 +9,7 @@ A collection of APIs built around Bun Shell that can be re-used in various CICD
 ## Examples
 
 - [`tahminator/instalock-web/.github/workflows`](https://github.com/tahminator/instalock-web/blob/main/.github), a monorepo with over 30k tracked users & 650 active in production.
-- [`tahminator/sapling/.github/workflows`](https://github.com/tahminator/instalock-web/blob/main/.github), an Express library that makes backend development easier & less painful (used in `instalock-web`)
+- [`tahminator/sapling/.github/workflows`](https://github.com/tahminator/sapling/blob/main/.github), an Express library that makes backend development easier & less painful (used in `instalock-web`)
 - [`tahminator/pipeline/src/internal`](https://github.com/tahminator/pipeline/blob/main/src/internal), which is used to help build, package & test this library
 
 ## Setup
@@ -35,10 +35,13 @@ bun run src/index.ts
 ```ts
 import {
   DockerClient,
+  EnvClient,
   GitHubClient,
   NPMClient,
+  PulumiClient,
   SonarScannerClient,
   Utils,
+  VersioningClient,
 } from "@tahminator/pipeline";
 ```
 
@@ -64,22 +67,6 @@ const client = await GitHubClient.createWithGithubAppToken({
   installationId: process.env.GH_INSTALLATION_ID!,
 });
 
-// requires gh app
-await client.createTag({
-  releaseType: "patch", // default is patch
-  // can also be automatically be inferred from env.GITHUB_REPOSITORY which is automatically injected in Actions
-  repositoryOverride: ["tahminator", "my-service"],
-});
-
-await client.createTag({
-  releaseType: "minor",
-  onPreTagCreate: async (tag) => {
-    // will set `version` key for all `package.json` excluding `node_modules/`
-    await Utils.updateAllPackageJsonsWithVersion(tag);
-    // you can write you own logic here if you would like
-  },
-});
-
 // output to env.GITHUB_OUTPUT to re-use outputs across steps, jobs, outputs, etc.
 // Hover over type in IDE to see more details
 await client.outputToGithubOutput({
@@ -98,10 +85,36 @@ await client.updateK8sTagWithPR({
   originRepo: ["tahminator", "pipeline"],
   manifestRepo: ["tahminator", "infra"],
 });
+
+await client.sendPrMessage({
+  owner: "tahminator",
+  repository: "pipeline",
+  prId: 123,
+  message: "Deployed and healthy.",
+});
+
+// use VersioningClient to compute your next semver tag.
+// look for `VersioningClient` section for how to configure / use
+const versioning = new VersioningClient(client, VersionUpdatingStrategy.JSTS);
+
+const nextTag =
+  // requires gh app
+  await client.createTag({
+    nextTag: await versioning.next("1.5.0", {
+      repositoryOverride: ["tahminator", "my-service"],
+    }),
+    repositoryOverride: ["tahminator", "my-service"],
+    onPreTagCreate: async (tag) => {
+      // update versions across your repo before tagging (strategy dependent)
+      await versioning.update(tag);
+      // you can write you own logic here if you would like
+    },
+  });
 ```
 
 ```ts
 // client cannot do most automations without getting skipped by CICD, but it can do many read operations and all CI operations just fine
+// uses GH_TOKEN from env
 const client = await GitHubClient.createWithDefaultCiToken();
 
 await client.outputToGithubOutput({
@@ -158,8 +171,8 @@ await npm.publish();
 await npm.publish(true);
 
 // publish to the beta dist-tag instead of latest
-// just like before, you should use `Utils.updateAllPackageJsonsWithVersion`
-// with `Utils.SemVar.validate(betaTag)` to set a valid version
+// validate versions with `Utils.SemVer.validate(...)`
+// and update versions with `VersioningClient.update(...)` if desired
 await npm.publish(false, true);
 ```
 
@@ -181,9 +194,10 @@ const backendClient = new SonarScannerClient({
     projectKey: "my-org_my-java-service",
     organization: "my-org",
     sourceCodeDir: "src/main/java",
-    additionalArgs: { // all args are automatically wrapped in `-Dsonar.${key}=${value}`
-      java.binaries: "target/classes",
-      coverage.jacoco.xmlReportPaths: "target/site/jacoco/jacoco.xml",
+    additionalArgs: {
+      // all args are automatically wrapped in `-Dsonar.${key}=${value}`
+      "java.binaries": "target/classes",
+      "coverage.jacoco.xmlReportPaths": "target/site/jacoco/jacoco.xml",
     },
   },
 });
@@ -203,7 +217,7 @@ const frontendClient = new SonarScannerClient({
     organization: "my-org",
     sourceCodeDir: "js/src",
     additionalArgs: {
-      javascript.lcov.reportPaths: "js/coverage/lcov.info",
+      "javascript.lcov.reportPaths": "js/coverage/lcov.info",
     },
   },
 });
@@ -221,21 +235,96 @@ const githubPrivateKey = await Utils.decodeBase64EncodedString(
   process.env.GH_PRIVATE_KEY_B64!,
 );
 
-// will read from git-crypt encrypted variable so long as git-crypt & gpg are setup
-// will only consume in memory
-const env = await Utils.getEnvVariables(["shared", "production"], {
-  baseDir: "apps/backend",
-});
-
 const shortId = Utils.generateShortId();
 
-await Utils.updateAllPackageJsonsWithVersion("1.2.3");
-
 if (await Utils.isCmdAvailable("gh")) {
   console.log(Utils.Colors.green(`gh is installed (${shortId})`));
 }
 
-if (Utils.Log.isDebug) {
-  console.log(env.DATABASE_URL);
-}
+if (!Utils.SemVer.validate("1.2.3")) throw new Error("invalid version");
+```
+
+### `EnvClient`
+
+Load environment variables from encrypted files and automatically mask them in GitHub Actions logs.
+
+Supports:
+
+- `EnvClientStrategy.SOPS` (YAML files decrypted via `sops`)
+- `EnvClientStrategy.GIT_CRYPT` (`.env` style files via `git-crypt unlock`)
+
+```ts
+const envClient = EnvClient.create(EnvClientStrategy.SOPS);
+
+// YAML only
+const env = await envClient.readFromEnv("production.yaml", {
+  baseDir: "apps/backend",
+});
+
+// `env` is a Record<string, string>
+console.log(env.DATABASE_URL);
+```
+
+```ts
+// will automatically decrypt files via `git-crypt unlock`
+const envClient = EnvClient.create(EnvClientStrategy.GIT_CRYPT);
+const env = await envClient.readFromEnv(".env.ci");
+```
+
+### `PulumiClient`
+
+Interface with Pulumi Automation API (local workspace strategy).
+
+```ts
+const client = await PulumiClient.create({
+  strategy: PulumiClientStrategy.AZURE,
+  stackName: "production",
+  workDir: "./infra",
+  envs: {
+    PULUMI_BACKEND_URL: process.env.PULUMI_BACKEND_URL!,
+    ARM_CLIENT_ID: process.env.ARM_CLIENT_ID,
+    ARM_CLIENT_SECRET: process.env.ARM_CLIENT_SECRET,
+    ARM_TENANT_ID: process.env.ARM_TENANT_ID,
+    ARM_SUBSCRIPTION_ID: process.env.ARM_SUBSCRIPTION_ID,
+  },
+});
+
+const preview = await client.preview({
+  diff: true,
+  rewriteStdoutToDiffFriendly: true,
+});
+
+console.log(preview.stdout);
+console.log(PulumiClient.parseChangeSumaryToPrettyTable(preview.changeSummary));
+```
+
+### `VersioningClient`
+
+Utilities to compute the next semver tag from GitHub and update versions in codebases.
+
+```ts
+const gh = await GitHubClient.createWithDefaultCiToken();
+
+const versioning = new VersioningClient(gh, VersionUpdatingStrategy.JSTS);
+
+// if your repo has no tags yet, this will return `1.0.0`
+// if `baseVersion` is provided, its patch number must be `0` (e.g. `1.5.0`)
+const next = await versioning.next("1.5.0");
+
+// update versions across your repo (strategy dependent)
+await versioning.update(next);
+```
+
+```ts
+// beta tags
+const gh = await GitHubClient.createWithDefaultCiToken();
+const versioning = new VersioningClient(gh, VersionUpdatingStrategy.JSTS);
+
+const sha = process.env.GITHUB_SHA!;
+const shortSha = sha.slice(0, 8);
+
+const beta = await versioning.nextBeta(shortSha);
+if (!Utils.SemVer.validate(beta)) throw new Error("invalid beta version");
+
+await versioning.update(beta);
 ```

package/dist/gh/client.d.ts

@@ -4,7 +4,6 @@ import { GitHubTagManager } from "./tag";
 export declare class GitHubClient {
     private readonly client;
     private readonly isExplicitToken;
-    static readonly BASE_VERSION = "1.0.0";
     private readonly tagManager;
     private readonly outputManager;
     private readonly prManager;

package/dist/gh/client.js

@@ -6,7 +6,6 @@ import { GitHubTagManager } from "./tag";
 export class GitHubClient {
     client;
     isExplicitToken;
-    static BASE_VERSION = GitHubTagManager.BASE_VERSION;
     tagManager;
     outputManager;
     prManager;

package/dist/gh/tag/index.d.ts

@@ -1,10 +1,8 @@
 import { Octokit } from "@octokit/rest";
-import semver from "semver";
 import type { OwnerString, RepoString } from "../../types";
 export declare class GitHubTagManager {
     private readonly client;
     private readonly isExplicitToken;
-    static readonly BASE_VERSION = "1.0.0";
     constructor(client: Octokit, isExplicitToken: boolean);
     private checkToken;
     /**
@@ -19,10 +17,12 @@ export declare class GitHubTagManager {
      * @note You **must** pass in a GitHub token because the regular Github bot token
      * cannot trigger actions (due to fear of recursion). You must either provide a GitHub App token or
      * a GitHub PAT.
+     *
+     * @note you should use `VersioningClient` to generate `nextTag`
      */
-    createTag({ repositoryOverride, releaseType, onPreTagCreate, }: {
+    createTag({ nextTag, repositoryOverride, onPreTagCreate, }: {
+        nextTag: string;
         repositoryOverride?: [OwnerString, RepoString];
-        releaseType?: semver.ReleaseType;
         onPreTagCreate?: (tag: string) => Promise<void>;
     }): Promise<void>;
     private parseRepository;

package/dist/gh/tag/index.js

@@ -4,7 +4,6 @@ import semver from "semver";
 export class GitHubTagManager {
     client;
     isExplicitToken;
-    static BASE_VERSION = "1.0.0";
     constructor(client, isExplicitToken) {
         this.client = client;
         this.isExplicitToken = isExplicitToken;
@@ -37,19 +36,12 @@ export class GitHubTagManager {
      * @note You **must** pass in a GitHub token because the regular Github bot token
      * cannot trigger actions (due to fear of recursion). You must either provide a GitHub App token or
      * a GitHub PAT.
+     *
+     * @note you should use `VersioningClient` to generate `nextTag`
      */
-    async createTag({ repositoryOverride, releaseType, onPreTagCreate, }) {
+    async createTag({ nextTag, repositoryOverride, onPreTagCreate, }) {
         this.checkToken();
         const [owner, repo] = this.parseRepository(repositoryOverride);
-        const lastTag = await this.getLatestTag({
-            repositoryOverride: [owner, repo],
-        });
-        const nextTag = lastTag ?
-            semver.inc(lastTag, releaseType ?? "patch")
-            : GitHubTagManager.BASE_VERSION;
-        if (!nextTag) {
-            throw new Error("Could not increment version");
-        }
         const { data: repository } = await this.client.rest.repos.get({
             owner,
             repo,

package/dist/index.d.ts

@@ -5,5 +5,6 @@ export * from "./sonar";
 export * from "./pulumi";
 export * from "./types";
 export * from "./env";
+export * from "./postgres";
 export * from "./utils";
 export * from "./versioning";

package/dist/index.js

@@ -5,5 +5,6 @@ export * from "./sonar";
 export * from "./pulumi";
 export * from "./types";
 export * from "./env";
+export * from "./postgres";
 export * from "./utils";
 export * from "./versioning";

package/dist/internal/create-tag/index.js

@@ -1,6 +1,7 @@
 import { EnvClient, EnvClientStrategy } from "../../env";
 import { GitHubClient } from "../../gh";
 import { Utils } from "../../utils";
+import { VersioningClient, VersionUpdatingStrategy } from "../../versioning";
 async function main() {
     const envClient = EnvClient.create(EnvClientStrategy.GIT_CRYPT);
     const { githubAppAppId, githubAppInstallationId, githubAppPrivateKeyB64 } = parseCiEnv(await envClient.readFromEnv(".env.ci"));
@@ -9,7 +10,10 @@ async function main() {
         installationId: githubAppInstallationId,
         privateKey: await Utils.decodeBase64EncodedString(githubAppPrivateKeyB64),
     });
+    const versioningClient = new VersioningClient(ghClient, VersionUpdatingStrategy.JSTS);
+    const rootPkgJson = await Bun.file("./package.json").json();
     await ghClient.createTag({
+        nextTag: await versioningClient.next(rootPkgJson.version),
         onPreTagCreate: async (tag) => {
             const file = Bun.file("./package.json");
             const pkg = await file.json();

package/dist/internal/upload-npm/beta/index.js

@@ -28,8 +28,7 @@ async function main() {
     const npmClient = await NPMClient.create();
     const versioningClient = new VersioningClient(ghClient, VersionUpdatingStrategy.JSTS);
     const shortSha = await getShortSha(sha);
-    const lastTag = (await ghClient.getLatestTag()) ?? GitHubClient.BASE_VERSION;
-    const betaVersion = `${lastTag}-beta.${shortSha}`;
+    const betaVersion = await versioningClient.nextBeta(shortSha);
     if (!Utils.SemVer.validate(betaVersion)) {
         throw new Error(`Generated invalid beta version: ${betaVersion}`);
     }

package/dist/postgres/client.d.ts

@@ -0,0 +1,11 @@
+import type { PostgresInternalState, PostgresState } from "./types";
+export declare class LocalPostgresClient {
+    private readonly iState;
+    private constructor();
+    static create(state: PostgresState): Promise<LocalPostgresClient>;
+    private static launch;
+    private static waitUntilReady;
+    get state(): PostgresInternalState;
+    [Symbol.asyncDispose](): Promise<void>;
+    cleanup(): Promise<void>;
+}

package/dist/postgres/client.js

@@ -0,0 +1,75 @@
+import { $, randomUUIDv7 } from "bun";
+import { Utils } from "../utils";
+export class LocalPostgresClient {
+    iState;
+    constructor(iState) {
+        this.iState = iState;
+    }
+    static async create(state) {
+        const iState = {
+            ...state,
+            user: "postgres",
+            password: "postgres",
+            port: 5432,
+            host: "127.0.0.1",
+            dockerName: `local-db-${randomUUIDv7()}`,
+        };
+        const hostPort = await this.launch(iState);
+        iState.port = hostPort;
+        await this.waitUntilReady(iState);
+        return new this(iState);
+    }
+    static async launch(iState) {
+        await $ `docker run -d \
+        --name ${iState.dockerName} \
+        -e POSTGRES_USER=${iState.user} \
+        -e POSTGRES_PASSWORD=${iState.password} \
+        -e POSTGRES_DB=${iState.database} \
+        -p 5432 \
+        mirror.gcr.io/library/postgres:16-alpine`;
+        const raw = (await $ `docker port ${iState.dockerName} 5432/tcp`.text()).trim();
+        const match = raw.match(/:(\d+)/);
+        if (!match) {
+            throw new Error(`Could not parse host port from: ${raw}`);
+        }
+        return Number(match[1]);
+    }
+    static async waitUntilReady(iState) {
+        console.log(`Waiting for ${iState.dockerName} to become ready.`);
+        const attempts = 30;
+        for (let i = 1; i <= attempts; i++) {
+            const check = await $ `docker exec ${iState.dockerName} pg_isready -U ${iState.user}`
+                .quiet()
+                .nothrow();
+            if (check.exitCode === 0) {
+                console.log(`${iState.dockerName} is ready`);
+                return;
+            }
+            console.log(`Waiting for ${iState.dockerName}... (${i}/${attempts})`);
+            await Bun.sleep(2000);
+        }
+        const msg = `${iState.dockerName} failed to launch`;
+        console.error(msg);
+        throw new Error(msg);
+    }
+    get state() {
+        return this.iState;
+    }
+    async [Symbol.asyncDispose]() {
+        await this.cleanup();
+    }
+    async cleanup() {
+        console.log(`Stopping and removing ${this.iState.dockerName} container...`);
+        if (Utils.Log.isDebug) {
+            console.log(Utils.Colors.brightMagenta("=== DB LOGS ==="));
+            const logs = await $ `docker logs ${this.iState.dockerName}`.text();
+            logs
+                .split("\n")
+                .filter((s) => s.length > 0)
+                .forEach((line) => console.log(Utils.Colors.brightMagenta(line)));
+            console.log(Utils.Colors.brightMagenta("=== DB LOGS END ==="));
+        }
+        await $ `docker stop ${this.iState.dockerName}`.quiet().nothrow();
+        await $ `docker rm ${this.iState.dockerName}`.quiet().nothrow();
+    }
+}

package/dist/postgres/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./types";

package/dist/postgres/index.js

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./types";

package/dist/postgres/types.d.ts

@@ -0,0 +1,10 @@
+export interface PostgresState {
+    database: string;
+}
+export interface PostgresInternalState extends PostgresState {
+    port: number;
+    host: string;
+    user: string;
+    password: string;
+    dockerName: string;
+}

package/dist/versioning/client.d.ts

@@ -23,4 +23,12 @@ export declare class VersioningClient implements IVersioningClient {
      * `baseVersion` must set patch number to `0`. (e.g. `1.0.0`, `1.5.0`, `2.0.0`, etc.)
      */
     next(baseVersion?: string, ...opts: Parameters<GitHubClient["getLatestTag"]>): Promise<string>;
+    /**
+     * generate next beta version tag using a `sha`.
+     *
+     * simply finds latest version from github and generates `{version}-beta.{sha}` to it.
+     *
+     * for example, `1.3.2-beta.58cf28bd`
+     */
+    nextBeta(sha: string, ...opts: Parameters<GitHubClient["getLatestTag"]>): Promise<string>;
 }

package/dist/versioning/client.js

@@ -67,4 +67,19 @@ export class VersioningClient {
         }
         return baseVersionSemver.toString();
     }
+    /**
+     * generate next beta version tag using a `sha`.
+     *
+     * simply finds latest version from github and generates `{version}-beta.{sha}` to it.
+     *
+     * for example, `1.3.2-beta.58cf28bd`
+     */
+    async nextBeta(sha, ...opts) {
+        const latestTag = await this.githubClient.getLatestTag(...opts);
+        if (!latestTag) {
+            throw new Error("You must upload a tag atleast once before generating a beta tag.");
+        }
+        const latest = this.parseOrThrow("latest tag from github", latestTag);
+        return `${latest.toString()}-beta.${sha}`;
+    }
 }

package/dist/versioning/types.d.ts

@@ -21,6 +21,16 @@ export interface IVersioningClient extends IVersionUpdatingClient {
      * `baseVersion` must set patch number to `0`. (e.g. `1.0.0`, `1.5.0`, `2.0.0`, etc.)
      */
     next(baseVersion?: string): Promise<string>;
+    /**
+     * generate next beta version tag.
+     *
+     * simply finds latest version from github and generates `{version}-beta.{sha}` to it.
+     *
+     * @note you may pass in the first 8 characters of `sha` if you choose.
+     *
+     * for example, `1.3.2-beta.58cf28bd`
+     */
+    nextBeta(sha: string): Promise<string>;
 }
 export interface IJavascriptPackageJsonVersionUpdatingClient extends IVersionUpdatingClient {
 }

package/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "author": "Tahmid Ahmed",
   "description": "A collection of Bun shell scripts that can be re-used in various CICD pipelines.",
-  "version": "1.0.57",
+  "version": "1.0.59-beta.2d7a142f",
   "repository": {
     "url": "git+https://github.com/tahminator/pipeline.git"
   },