@hellopearl/dv-gitlab 0.1.0

package/bin/dv-gitlab.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+import { run } from '../src/cli.mjs';
+
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@hellopearl/dv-gitlab",
+  "version": "0.1.0",
+  "description": "Unified GitLab CI tooling -- MR comments, pipeline triggers, preview env management",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "bin": "bin/dv-gitlab.mjs",
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "deps": "dv-deps-runner",
+    "format": "dv-prettier-runner",
+    "format:check": "dv-prettier-runner --check",
+    "lint": "dv-lint-runner --server",
+    "test:unit": "dv-test-runner --type=unit",
+    "test:unit:cover": "dv-test-runner --type=unit --coverage"
+  },
+  "jest": {
+    "coverageThreshold": {
+      "global": {
+        "statements": 80,
+        "branches": 80,
+        "functions": 80,
+        "lines": 80
+      }
+    }
+  },
+  "engines": {
+    "node": ">=22",
+    "yarn": ">=4.14.1"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@hellopearl/dv-deps": "*",
+    "@hellopearl/dv-lint": "*",
+    "@hellopearl/dv-prettier": "*",
+    "@hellopearl/dv-test": "*"
+  },
+  "gitHead": "2da7b9fc23900bbaf9c4fcf6042ecec76d538bc2"
+}

package/src/cli.mjs

@@ -0,0 +1,84 @@
+import { cleanupBranch } from './commands/cleanup-branch.mjs';
+import { postComment } from './commands/post-comment.mjs';
+import { postbuild } from './commands/postbuild.mjs';
+import { triggerPipeline } from './commands/trigger-pipeline.mjs';
+import { validateToken } from './commands/validate-token.mjs';
+import { log } from './lib/logger.mjs';
+
+const COMMANDS = {
+  'cleanup-branch': cleanupBranch,
+  'post-comment': postComment,
+  postbuild,
+  'trigger-pipeline': triggerPipeline,
+  'validate-token': validateToken,
+};
+
+/**
+ * @param {string[]} args
+ * @returns {Record<string, string>}
+ */
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith('--')) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = 'true';
+      }
+    }
+  }
+  return flags;
+}
+
+function printUsage() {
+  log(`
+dv-gitlab -- Unified GitLab CI tooling
+
+Commands:
+  postbuild          Amplify post-build orchestrator (branch routing + comment + trigger)
+  post-comment       Post markdown note on a GitLab MR
+  trigger-pipeline   Trigger a GitLab CI pipeline
+  validate-token     Check if a GitLab PAT is valid
+  cleanup-branch     Delete an Amplify preview branch
+
+Options:
+  --help             Show this help message
+
+All commands read configuration from environment variables.
+Use --<flag> <value> to override for local testing.
+`);
+}
+
+/**
+ * @param {string[]} argv
+ */
+export async function run(argv) {
+  const [command, ...args] = argv;
+
+  if (!command || command === '--help' || command === '-h') {
+    printUsage();
+    process.exit(0);
+  }
+
+  const handler = COMMANDS[command];
+  if (!handler) {
+    log(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+  }
+
+  try {
+    await handler(parseFlags(args));
+  } catch (err) {
+    log(`[error] ${err.message}`);
+    if (process.env.DV_GITLAB_DEBUG === 'true') {
+      console.error(err.stack);
+    }
+    process.exit(1);
+  }
+}

package/src/commands/cleanup-branch.mjs

@@ -0,0 +1,40 @@
+import { AmplifyClient } from '../lib/amplify-client.mjs';
+import { debug, log } from '../lib/logger.mjs';
+
+/**
+ * Deletes an Amplify preview branch environment.
+ * Intended for use in a GitLab CI .post stage on MR merge.
+ * @param {Record<string, string>} flags
+ */
+export async function cleanupBranch(flags) {
+  const branch =
+    flags.branch ||
+    process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME ||
+    process.env.AWS_BRANCH ||
+    '';
+  const appId = flags['app-id'] || process.env.AWS_APP_ID || '';
+  const region = flags.region || process.env.AWS_DEFAULT_REGION || 'us-east-1';
+
+  if (!branch) {
+    throw new Error(
+      'No branch specified. Set CI_MERGE_REQUEST_SOURCE_BRANCH_NAME or pass --branch',
+    );
+  }
+  if (!appId) {
+    throw new Error('No Amplify app ID. Set AWS_APP_ID or pass --app-id');
+  }
+
+  debug(`cleanup-branch branch=${branch} appId=${appId} region=${region}`);
+
+  const amplifyBranch = branch.toLowerCase().replace(/\//g, '-');
+  log(`[cleanup] Deleting Amplify branch: ${amplifyBranch} (app=${appId})`);
+
+  const client = new AmplifyClient({ appId, region });
+  const ok = await client.deleteBranch(amplifyBranch);
+
+  if (ok) {
+    log(`[cleanup] Branch ${amplifyBranch} removed successfully`);
+  } else {
+    throw new Error(`Failed to delete Amplify branch: ${amplifyBranch}`);
+  }
+}

package/src/commands/post-comment.mjs

@@ -0,0 +1,85 @@
+import { GitLabClient } from '../lib/gitlab-client.mjs';
+import { debug, log } from '../lib/logger.mjs';
+import { renderTemplate } from '../lib/template.mjs';
+
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+function camelCase(str) {
+  return str.toLowerCase().replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * Post a markdown note on a GitLab MR.
+ * Supports either --body for raw markdown or --template for template rendering.
+ * @param {Record<string, string>} flags
+ */
+export async function postComment(flags) {
+  const token =
+    flags.token ||
+    process.env.GITLAB_API_TOKEN ||
+    process.env.GITLAB_SO_API_TOKEN ||
+    '';
+  const projectId =
+    flags['project-id'] ||
+    process.env.GITLAB_PROJECT_ID ||
+    process.env.GITLAB_SECOND_OPINION_PROJECT_ID ||
+    '';
+  const mrIid = flags['mr-iid'] || '';
+  const branch = flags.branch || process.env.AWS_BRANCH || '';
+
+  if (!token) {
+    throw new Error('No GitLab token. Set GITLAB_API_TOKEN or pass --token');
+  }
+  if (!projectId) {
+    throw new Error(
+      'No project ID. Set GITLAB_PROJECT_ID or pass --project-id',
+    );
+  }
+
+  const client = new GitLabClient({ token });
+  let iid = mrIid ? Number(mrIid) : null;
+
+  if (!iid && branch) {
+    debug(`Looking up open MR for branch=${branch}`);
+    const mr = await client.findOpenMr(projectId, branch);
+    if (!mr) {
+      throw new Error(`No open MR found for branch: ${branch}`);
+    }
+    iid = mr.iid;
+  }
+
+  if (!iid) {
+    throw new Error('No MR IID. Pass --mr-iid or --branch to auto-detect');
+  }
+
+  let body = flags.body || '';
+
+  if (!body && flags.template) {
+    const vars = {};
+    for (const [key, value] of Object.entries(flags)) {
+      if (key !== 'template' && key !== 'token' && key !== 'project-id') {
+        vars[key] = value;
+      }
+    }
+    for (const [key, value] of Object.entries(process.env)) {
+      const lower = key.toLowerCase().replace(/_/g, '-');
+      if (!vars[lower]) {
+        vars[camelCase(key)] = value || '';
+      }
+    }
+    body = renderTemplate(flags.template, vars);
+  }
+
+  if (!body) {
+    throw new Error('No comment body. Pass --body "..." or --template <name>');
+  }
+
+  const ok = await client.postNote(projectId, iid, body);
+  if (ok) {
+    log(`Comment posted on MR !${iid}`);
+  } else {
+    throw new Error(`Failed to post comment on MR !${iid}`);
+  }
+}

package/src/commands/postbuild.mjs

@@ -0,0 +1,253 @@
+import { GitLabClient } from '../lib/gitlab-client.mjs';
+import { debug, log } from '../lib/logger.mjs';
+import { renderTemplate } from '../lib/template.mjs';
+
+const PRODUCTION_BRANCHES = ['main', 'master', 'prod', 'sandbox'];
+const QA_BRANCHES = ['development', 'develop', 'stage'];
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+function env(name) {
+  const val = process.env[name] || '';
+  if (!val) {
+    debug(`env ${name} is empty`);
+  }
+  return val;
+}
+
+/**
+ * @param {string} path
+ * @returns {Promise<boolean>}
+ */
+async function dirExists(path) {
+  try {
+    const { stat } = await import('node:fs/promises');
+    const s = await stat(path);
+    return s.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function resolveToken() {
+  return process.env.GITLAB_API_TOKEN || process.env.GITLAB_SO_API_TOKEN || '';
+}
+
+function resolveProjectId() {
+  return (
+    process.env.GITLAB_PROJECT_ID ||
+    process.env.GITLAB_SECOND_OPINION_PROJECT_ID ||
+    ''
+  );
+}
+
+async function triggerPipelineSimple() {
+  const pipelineUrl = env('QA_PIPELINE_URL');
+  const token = process.env.QA_PIPELINE_TRIGGER_TOKEN || resolveToken();
+
+  if (!token || !pipelineUrl) {
+    log('[postbuild] missing pipeline trigger config -- skipping');
+    return;
+  }
+
+  const payload = {
+    inputs: {
+      capture: process.env.QA_PIPELINE_CAPTURE || '',
+      environment: process.env.QA_PIPELINE_ENVIRONMENT || '',
+      project: process.env.QA_PIPELINE_PROJECT || '',
+      scope: process.env.QA_PIPELINE_SCOPE || '',
+    },
+    ref: process.env.QA_PIPELINE_REF || '',
+  };
+
+  debug(`[trigger-simple] payload=${JSON.stringify(payload)}`);
+
+  const res = await fetch(pipelineUrl, {
+    body: JSON.stringify(payload),
+    headers: {
+      'Content-Type': 'application/json',
+      'PRIVATE-TOKEN': token,
+    },
+    method: 'POST',
+  });
+
+  if (res.ok) {
+    log(`[postbuild] QA pipeline triggered (http=${res.status})`);
+  } else {
+    log(`[postbuild] QA pipeline trigger failed (http=${res.status})`);
+  }
+}
+
+/**
+ * @param {{token: string, projectId: string, mrIid: string, branch: string, appId: string}} opts
+ * @returns {Promise<{id: number, webUrl: string} | null>}
+ */
+async function triggerPipelinePreview({
+  token,
+  projectId,
+  mrIid,
+  branch,
+  appId,
+}) {
+  const pipelineUrl = process.env.QA_PIPELINE_URL;
+  const triggerToken = process.env.QA_PIPELINE_TRIGGER_TOKEN || token;
+
+  if (!pipelineUrl) {
+    log('[postbuild] QA_PIPELINE_URL not set -- skipping trigger');
+    return null;
+  }
+
+  const payload = {
+    inputs: {
+      capture: process.env.QA_PIPELINE_CAPTURE || '',
+      environment: process.env.QA_PIPELINE_ENVIRONMENT || '',
+      project: process.env.QA_PIPELINE_PROJECT || '',
+      scope: process.env.QA_PIPELINE_SCOPE || '',
+    },
+    ref: process.env.QA_PIPELINE_REF || '',
+    variables: [
+      { key: 'SOURCE_PROJECT_ID', value: projectId },
+      { key: 'SOURCE_MR_IID', value: mrIid },
+      { key: 'BRANCH', value: branch },
+      { key: 'AMPLIFY_APP_ID', value: appId },
+    ],
+  };
+
+  debug(`[trigger-preview] payload=${JSON.stringify(payload)}`);
+
+  const res = await fetch(pipelineUrl, {
+    body: JSON.stringify(payload),
+    headers: {
+      'Content-Type': 'application/json',
+      'PRIVATE-TOKEN': triggerToken,
+    },
+    method: 'POST',
+  });
+
+  debug(`[trigger-preview] http=${res.status}`);
+
+  if (!res.ok) {
+    log(`[postbuild] pipeline trigger failed (http=${res.status})`);
+    return null;
+  }
+
+  const data = await res.json();
+  log(`[postbuild] pipeline triggered id=${data.id} url=${data.web_url}`);
+  return { id: data.id, webUrl: data.web_url };
+}
+
+/**
+ * Full postbuild orchestrator.
+ * Routes by branch type: production (exit), QA (trigger only), feature (comment + trigger).
+ */
+export async function postbuild() {
+  const branch = env('AWS_BRANCH');
+  const commitId = env('AWS_COMMIT_ID');
+  const appId = env('AWS_APP_ID');
+  const jobId = env('AWS_JOB_ID');
+  const region = env('AWS_DEFAULT_REGION');
+
+  log(
+    `[postbuild] branch=${branch} commit=${commitId} app=${appId} job=${jobId}`,
+  );
+
+  if (PRODUCTION_BRANCHES.includes(branch)) {
+    log('[postbuild] route=production -- skipping');
+    return;
+  }
+
+  if (QA_BRANCHES.includes(branch)) {
+    log('[postbuild] route=qa');
+    if (process.env.QA_POSTBUILD_ENABLED !== 'true') {
+      log('[postbuild] QA_POSTBUILD_ENABLED not set -- skipping');
+      return;
+    }
+    await triggerPipelineSimple();
+    return;
+  }
+
+  log('[postbuild] route=feature');
+
+  const token = resolveToken();
+  if (!token) {
+    log('[postbuild] no GitLab token available -- skipping');
+    return;
+  }
+
+  const projectId = resolveProjectId();
+  const client = new GitLabClient({ token });
+  const mr = await client.findOpenMr(projectId, branch);
+
+  if (!mr) {
+    log(`[postbuild] no open MR for branch=${branch} -- skipping`);
+    return;
+  }
+
+  if (mr.description.includes('skip:ci')) {
+    log('[postbuild] MR description contains "skip:ci" -- skipping');
+    return;
+  }
+
+  const previewBranch = branch.toLowerCase().replace(/\//g, '-');
+  const previewDomain = process.env.PREVIEW_DOMAIN || '';
+  const previewUrl = previewDomain
+    ? `https://${previewBranch}.${previewDomain}`
+    : '';
+  const shortCommit = commitId.slice(0, 8);
+
+  const buildDir = process.env.CODEBUILD_SRC_DIR
+    ? `${process.env.CODEBUILD_SRC_DIR}/build`
+    : 'build';
+
+  const buildExists = await dirExists(buildDir);
+  const templateName = buildExists ? 'preview-ready' : 'preview-failed';
+
+  const commentBody = renderTemplate(templateName, {
+    appId,
+    branch,
+    commitId: shortCommit,
+    jobId,
+    previewUrl,
+    region,
+  });
+
+  const posted = await client.postNote(projectId, mr.iid, commentBody);
+  if (posted) {
+    log(`[postbuild] preview comment posted on MR !${mr.iid}`);
+  } else {
+    log('[postbuild] failed to post preview comment');
+    return;
+  }
+
+  if (!buildExists) {
+    log('[postbuild] build dir missing -- skipping pipeline trigger');
+    return;
+  }
+
+  const triggerResult = await triggerPipelinePreview({
+    appId,
+    branch,
+    mrIid: mr.iid.toString(),
+    projectId: projectId.toString(),
+    token,
+  });
+
+  if (triggerResult) {
+    const triggerBody = renderTemplate('pipeline-triggered', {
+      environment: process.env.QA_PIPELINE_ENVIRONMENT || '',
+      pipelineId: triggerResult.id.toString(),
+      pipelineUrl: triggerResult.webUrl,
+      project: process.env.QA_PIPELINE_PROJECT || '',
+      ref: process.env.QA_PIPELINE_REF || '',
+    });
+
+    const triggerPosted = await client.postNote(projectId, mr.iid, triggerBody);
+    if (triggerPosted) {
+      log('[postbuild] automation trigger comment posted');
+    } else {
+      log('[postbuild] failed to post trigger comment');
+    }
+  }
+}

package/src/commands/trigger-pipeline.mjs

@@ -0,0 +1,85 @@
+import { debug, log } from '../lib/logger.mjs';
+
+/**
+ * Triggers a GitLab CI pipeline via API.
+ * @param {Record<string, string>} flags
+ */
+export async function triggerPipeline(flags) {
+  const url = flags.url || process.env.QA_PIPELINE_URL || '';
+  const token =
+    flags.token ||
+    process.env.QA_PIPELINE_TRIGGER_TOKEN ||
+    process.env.GITLAB_API_TOKEN ||
+    '';
+  const ref = flags.ref || process.env.QA_PIPELINE_REF || '';
+
+  if (!url) {
+    throw new Error('No pipeline URL. Set QA_PIPELINE_URL or pass --url');
+  }
+  if (!token) {
+    throw new Error(
+      'No trigger token. Set QA_PIPELINE_TRIGGER_TOKEN or pass --token',
+    );
+  }
+
+  const payload = {
+    inputs: {
+      capture: flags.capture || process.env.QA_PIPELINE_CAPTURE || '',
+      environment:
+        flags.environment || process.env.QA_PIPELINE_ENVIRONMENT || '',
+      project: flags.project || process.env.QA_PIPELINE_PROJECT || '',
+      scope: flags.scope || process.env.QA_PIPELINE_SCOPE || '',
+    },
+    ref,
+  };
+
+  const variables = [];
+  if (flags['source-project-id']) {
+    variables.push({
+      key: 'SOURCE_PROJECT_ID',
+      value: flags['source-project-id'],
+    });
+  }
+  if (flags['source-mr-iid']) {
+    variables.push({
+      key: 'SOURCE_MR_IID',
+      value: flags['source-mr-iid'],
+    });
+  }
+  if (flags.branch || process.env.AWS_BRANCH) {
+    variables.push({
+      key: 'BRANCH',
+      value: flags.branch || process.env.AWS_BRANCH,
+    });
+  }
+  if (flags['app-id'] || process.env.AWS_APP_ID) {
+    variables.push({
+      key: 'AMPLIFY_APP_ID',
+      value: flags['app-id'] || process.env.AWS_APP_ID,
+    });
+  }
+
+  if (variables.length) {
+    payload.variables = variables;
+  }
+
+  debug(`trigger-pipeline payload=${JSON.stringify(payload)}`);
+
+  const res = await fetch(url, {
+    body: JSON.stringify(payload),
+    headers: {
+      'Content-Type': 'application/json',
+      'PRIVATE-TOKEN': token,
+    },
+    method: 'POST',
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    debug(`trigger-pipeline response=${text}`);
+    throw new Error(`Pipeline trigger failed (http=${res.status})`);
+  }
+
+  const data = await res.json();
+  log(`Pipeline triggered: id=${data.id} url=${data.web_url}`);
+}

package/src/commands/validate-token.mjs

@@ -0,0 +1,30 @@
+import { GitLabClient } from '../lib/gitlab-client.mjs';
+import { log } from '../lib/logger.mjs';
+
+/**
+ * Validates a GitLab PAT by calling the self-introspection endpoint.
+ * Exits 0 if valid, 1 if invalid.
+ * @param {Record<string, string>} flags
+ */
+export async function validateToken(flags) {
+  const token =
+    flags.token ||
+    process.env.GITLAB_API_TOKEN ||
+    process.env.GITLAB_SO_API_TOKEN ||
+    '';
+
+  if (!token) {
+    log('No token provided. Set GITLAB_API_TOKEN or pass --token');
+    process.exit(1);
+  }
+
+  const client = new GitLabClient({ token });
+  const valid = await client.validateToken();
+
+  if (valid) {
+    log('Token is valid');
+  } else {
+    log('Token is invalid or expired');
+    process.exit(1);
+  }
+}

package/src/index.mjs

@@ -0,0 +1,4 @@
+export { run } from './cli.mjs';
+export { GitLabClient } from './lib/gitlab-client.mjs';
+export { AmplifyClient } from './lib/amplify-client.mjs';
+export { log, debug } from './lib/logger.mjs';

package/src/lib/amplify-client.mjs

@@ -0,0 +1,45 @@
+import { debug, log } from './logger.mjs';
+
+const AWS_AMPLIFY_BASE = 'https://amplify.{region}.amazonaws.com';
+
+export class AmplifyClient {
+  /** @param {{ region: string, appId: string }} opts */
+  constructor({ region, appId }) {
+    this.region = region;
+    this.appId = appId;
+    this.baseUrl = AWS_AMPLIFY_BASE.replace('{region}', region);
+  }
+
+  /**
+   * Deletes a preview branch from Amplify via AWS SDK-like REST call.
+   * Uses AWS Signature v4 from the environment (IAM role / env creds).
+   * In practice this should be called from an environment where
+   * @aws-sdk/client-amplify is available; this fallback uses fetch.
+   * @param {string} branchName
+   * @returns {Promise<boolean>}
+   */
+  async deleteBranch(branchName) {
+    debug(`deleteBranch appId=${this.appId} branch=${branchName}`);
+
+    try {
+      const { AmplifyClient: AwsAmplify, DeleteBranchCommand } = await import(
+        '@aws-sdk/client-amplify' // eslint-disable-line import/no-unresolved
+      );
+      const client = new AwsAmplify({ region: this.region });
+      const command = new DeleteBranchCommand({
+        appId: this.appId,
+        branchName,
+      });
+      await client.send(command);
+      log(`Deleted Amplify branch: ${branchName}`);
+      return true;
+    } catch (err) {
+      if (err.name === 'NotFoundException') {
+        log(`Branch ${branchName} not found (already deleted)`);
+        return true;
+      }
+      log(`Failed to delete branch ${branchName}: ${err.message}`);
+      return false;
+    }
+  }
+}

package/src/lib/gitlab-client.mjs

@@ -0,0 +1,107 @@
+import { debug } from './logger.mjs';
+
+const GITLAB_API_BASE = 'https://gitlab.com/api/v4';
+
+export class GitLabClient {
+  /** @param {{ token: string, apiBase?: string }} opts */
+  constructor({ token, apiBase }) {
+    this.token = token;
+    this.apiBase = apiBase || GITLAB_API_BASE;
+  }
+
+  /**
+   * Validates the PAT by calling the self-introspection endpoint.
+   * @returns {Promise<boolean>}
+   */
+  async validateToken() {
+    const res = await this._fetch(
+      `${this.apiBase}/personal_access_tokens/self`,
+    );
+    debug(`validate_token http=${res.status}`);
+    return res.ok;
+  }
+
+  /**
+   * Finds the first open MR for a given source branch.
+   * @param {string} projectId
+   * @param {string} branch
+   * @returns {Promise<{iid: number, description: string} | null>}
+   */
+  async findOpenMr(projectId, branch) {
+    const encoded = encodeURIComponent(branch);
+    const url = `${this.apiBase}/projects/${projectId}/merge_requests?source_branch=${encoded}&state=opened`;
+    debug(`findOpenMr GET ${url}`);
+
+    const res = await this._fetch(url);
+    if (!res.ok) {
+      debug(`findOpenMr failed http=${res.status}`);
+      return null;
+    }
+
+    const mrs = await res.json();
+    if (!mrs.length) {
+      return null;
+    }
+    return { description: mrs[0].description || '', iid: mrs[0].iid };
+  }
+
+  /**
+   * Posts a markdown note on an MR.
+   * @param {string} projectId
+   * @param {number} mrIid
+   * @param {string} body
+   * @returns {Promise<boolean>}
+   */
+  async postNote(projectId, mrIid, body) {
+    const url = `${this.apiBase}/projects/${projectId}/merge_requests/${mrIid}/notes`;
+    debug(`postNote POST ${url}`);
+
+    const res = await this._fetch(url, {
+      body: JSON.stringify({ body }),
+      headers: { 'Content-Type': 'application/json' },
+      method: 'POST',
+    });
+
+    debug(`postNote http=${res.status}`);
+    return res.ok;
+  }
+
+  /**
+   * Triggers a pipeline via the GitLab API.
+   * @param {string} url - full pipeline trigger URL
+   * @param {object} payload
+   * @returns {Promise<{ok: boolean, id?: number, webUrl?: string}>}
+   */
+  async triggerPipeline(url, payload) {
+    debug(`triggerPipeline POST ${url}`);
+
+    const res = await fetch(url, {
+      body: JSON.stringify(payload),
+      headers: {
+        'Content-Type': 'application/json',
+        'PRIVATE-TOKEN': this.token,
+      },
+      method: 'POST',
+    });
+
+    debug(`triggerPipeline http=${res.status}`);
+
+    if (!res.ok) {
+      return { ok: false };
+    }
+
+    const data = await res.json();
+    return { id: data.id, ok: true, webUrl: data.web_url };
+  }
+
+  /** @param {string} url @param {RequestInit} [opts] */
+  _fetch(url, opts = {}) {
+    return fetch(url, {
+      ...opts,
+      headers: {
+        'PRIVATE-TOKEN': this.token,
+        ...opts.headers,
+      },
+    });
+  }
+}

package/src/lib/logger.mjs

@@ -0,0 +1,16 @@
+/**
+ * @param {string} message
+ */
+export function log(message) {
+  console.log(message);
+}
+
+/**
+ * Only prints when DV_GITLAB_DEBUG=true.
+ * @param {string} message
+ */
+export function debug(message) {
+  if (process.env.DV_GITLAB_DEBUG === 'true') {
+    console.log(`[debug] ${message}`);
+  }
+}

package/src/lib/template.mjs

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = resolve(__dirname, '../templates');
+
+/**
+ * Renders a template file with variable interpolation.
+ * Template vars use `{{varName}}` syntax.
+ * @param {string} templateName - filename without extension (e.g. 'preview-ready')
+ * @param {Record<string, string>} vars
+ * @returns {string}
+ */
+export function renderTemplate(templateName, vars) {
+  const filePath = resolve(TEMPLATES_DIR, `${templateName}.md`);
+  let content = readFileSync(filePath, 'utf-8');
+
+  for (const [key, value] of Object.entries(vars)) {
+    content = content.replaceAll(`{{${key}}}`, value || '');
+  }
+
+  content = content.replace(/\{\{[^}]+\}\}/g, '');
+
+  return content;
+}

package/src/templates/pipeline-triggered.md

@@ -0,0 +1,12 @@
+## 🔄 Automation Pipeline Triggered
+
+| | |
+|---|---|
+| **Pipeline** | [#{{pipelineId}}]({{pipelineUrl}}) |
+| **Project** | `{{project}}` |
+| **Ref** | `{{ref}}` |
+| **Environment** | `{{environment}}` |
+
+---
+
+Results will be posted here once the pipeline completes.

package/src/templates/preview-failed.md

@@ -0,0 +1,10 @@
+## ❌ Preview Build Failed
+
+| | |
+|---|---|
+| **Branch** | `{{branch}}` |
+| **Commit** | `{{commitId}}` |
+
+---
+
+The Amplify preview build did not complete successfully. Check the [Amplify Console](https://{{region}}.console.aws.amazon.com/amplify/home#/{{appId}}/{{branch}}) for details.

package/src/templates/preview-ready.md

@@ -0,0 +1,18 @@
+## 🚀 Preview Environment Ready
+
+| | |
+|---|---|
+| **Branch** | `{{branch}}` |
+| **Commit** | `{{commitId}}` |
+| **Preview URL** | [{{previewUrl}}]({{previewUrl}}) |
+
+---
+
+<details>
+<summary>Build details</summary>
+
+- **App ID:** `{{appId}}`
+- **Job ID:** `{{jobId}}`
+- **Region:** `{{region}}`
+
+</details>