@alwaysmeticulous/cli 2.326.0 → 2.327.0

package/dist/commands/onboard/templates/docs/additional-guides/backend-recorder.ts

@@ -0,0 +1,340 @@
+import { METICULOUS_BACKEND_SETUP_CALENDLY_LINK } from "src/lib/next/next.constants";
+import {
+  ADDITIONAL_GUIDES,
+  NEXTJS_APP_ROUTER_ADDITIONAL_SETUP_URL,
+} from "src/lib/utils/internal-urls/docs-urls.utils";
+
+const BACKEND_RECORDER_PACKAGE = "@alwaysmeticulous/backend-recorder-launcher";
+const WORKERD_RECORDER_PACKAGE = "@alwaysmeticulous/backend-recorder-workerd";
+
+const BOOK_A_CALL_TIP = `If you have any issues setting up the backend recorder then click [here](${METICULOUS_BACKEND_SETUP_CALENDLY_LINK}) to book a call with us.`;
+
+export const document = `---
+{
+  "title": "Install the backend recorder"
+}
+---
+
+# {% $frontmatter.title %}
+
+The backend recorder captures the server side of your users' sessions. It intercepts HTTP requests and responses in your Node.js
+app using OpenTelemetry approach and exports them to Meticulous, where they are used to stub out backend calls during replays. This means
+Meticulous can replay sessions accurately even when they depend on data returned by your own API.
+
+The backend recorder is installed via the [\`${BACKEND_RECORDER_PACKAGE}\`](https://www.npmjs.com/package/${BACKEND_RECORDER_PACKAGE})
+package from the Meticulous SDK. It is complementary to the [frontend recorder](${ADDITIONAL_GUIDES.INSTALL_RECORDER_SCRIPT_FOR_BACKEND_TESTING_URL})
+— install the frontend recorder to capture user activity in the browser, and the backend recorder to capture the matching server-side requests.
+
+{% callout_card variant="info" title="When do I need the backend recorder?" %}
+The backend recorder is only required when your app uses **server-side rendering (SSR)**. In SSR apps, data is fetched on the server
+before the page reaches the browser, so the frontend recorder never sees those requests — the backend recorder captures them instead
+so Meticulous can stub them during replay. If your app renders entirely on the client (e.g. a standard SPA), the frontend recorder
+already captures every request and the backend recorder is not needed. ${BOOK_A_CALL_TIP}
+{% /callout_card %}
+
+## 1. Install the package
+
+\`\`\`bash
+npm install ${BACKEND_RECORDER_PACKAGE}
+\`\`\`
+
+The recorder must be loaded **before** your application code so it can patch Node.js' HTTP modules before any requests are made.
+Pick the option below that matches your setup.
+
+## 2. Initialize the recorder
+
+{% tabs direction="grid" noTabSelectedByDefault=true %}
+{% tab label="Next.js" %}
+## Next.js
+
+Next.js loads the file named \`instrumentation.ts\` (or \`instrumentation.js\`) at the root of your project before the rest of your app
+boots. Initialize the recorder from its \`register\` hook, guarding on the Node.js runtime so it never runs in the Edge runtime or the browser:
+
+{% code_with_project_selector %}
+\`\`\`ts
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const { initBackendRecorder } = await import(
+      "${BACKEND_RECORDER_PACKAGE}"
+    );
+    await initBackendRecorder({
+      meticulousProjectName: "{% project_name /%}",
+      recordingToken: "{% project_recording_token /%}",
+    });
+  }
+}
+\`\`\`
+{% /code_with_project_selector %}
+
+Mark the package as an external package so Next.js does not try to bundle it. In \`next.config.js\`:
+
+\`\`\`js
+// next.config.js
+module.exports = {
+  serverExternalPackages: ["${BACKEND_RECORDER_PACKAGE}"],
+};
+\`\`\`
+
+If you are using the App Router, also follow the [additional App Router setup](${NEXTJS_APP_ROUTER_ADDITIONAL_SETUP_URL}) to ensure
+Meticulous can correctly test your app.
+
+${BOOK_A_CALL_TIP}
+{% /tab %}
+
+{% tab label="TanStack Start" %}
+## TanStack Start
+
+TanStack Start's server entry point (\`src/server.ts\` by default) is the first server module that runs, so it's the right place
+to load the recorder. Create a separate \`src/instrumentation.ts\` file that initializes it, then import that file as the very
+first import in \`src/server.ts\` — ahead of the \`@tanstack/react-start/server-entry\` import — so the recorder patches Node's
+HTTP modules before any request-handling code runs:
+
+{% code_with_project_selector %}
+\`\`\`ts
+// src/instrumentation.ts
+import { initBackendRecorder } from "${BACKEND_RECORDER_PACKAGE}";
+
+await initBackendRecorder({
+  meticulousProjectName: "{% project_name /%}",
+  recordingToken: "{% project_recording_token /%}",
+});
+\`\`\`
+{% /code_with_project_selector %}
+
+\`\`\`ts
+// src/server.ts
+import "./instrumentation";
+
+import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
+
+export default createServerEntry({
+  fetch(request) {
+    return handler.fetch(request);
+  },
+});
+\`\`\`
+
+If your build ends up bundling \`${BACKEND_RECORDER_PACKAGE}\` into the server output, mark it as external in your Vite/Nitro
+server config so it keeps patching the real Node.js \`http\`/\`https\` modules rather than a bundled copy. ${BOOK_A_CALL_TIP}
+{% /tab %}
+
+{% tab label="Node.js (instrumentation file)" %}
+## Node.js
+
+Create an \`instrumentation.js\` file at the root of your project that initializes the recorder:
+
+{% code_with_project_selector %}
+\`\`\`js
+// instrumentation.js
+const { initBackendRecorder } = require("${BACKEND_RECORDER_PACKAGE}");
+
+initBackendRecorder({
+  meticulousProjectName: "{% project_name /%}",
+  recordingToken: "{% project_recording_token /%}",
+});
+\`\`\`
+{% /code_with_project_selector %}
+
+Start your app with the \`--require\` flag so the recorder is loaded before your application code:
+
+\`\`\`bash
+node --require ./instrumentation.js app.js
+\`\`\`
+
+${BOOK_A_CALL_TIP}
+{% /tab %}
+
+{% tab label="Cloudflare Workers" %}
+## Cloudflare Workers
+
+Workers run on the workerd runtime rather than Node.js, so the Node backend recorder above cannot be loaded in-process
+(skip step 1 — the \`${BACKEND_RECORDER_PACKAGE}\` package is not used here). Instead, Meticulous records during local
+development (\`wrangler dev\`) with a two-part setup:
+
+- A lightweight **shim** (\`${WORKERD_RECORDER_PACKAGE}\`) wraps your Worker's fetch handler and captures inbound requests
+  plus outgoing \`fetch\` calls. Outgoing requests still go directly to their destination — the recorder is never in the
+  request path — and when no sidecar is configured the shim is a complete no-op, so it is safe to keep in deployed code.
+- The **Meticulous recorder sidecar**, a small Node process on your dev machine started by the Meticulous CLI, receives
+  those events and uploads them to Meticulous as backend recordings.
+
+Install the shim and wrap your Worker's handler:
+
+\`\`\`bash
+npm install ${WORKERD_RECORDER_PACKAGE}
+\`\`\`
+
+\`\`\`ts
+import { withMeticulous } from "${WORKERD_RECORDER_PACKAGE}";
+
+export default withMeticulous({
+  async fetch(request, env, ctx) {
+    // your app
+  },
+});
+\`\`\`
+
+Enable the \`nodejs_als\` compatibility flag in your \`wrangler.toml\` (if you already use \`nodejs_compat\` — e.g. for
+TanStack Start — you're done, it includes it):
+
+\`\`\`toml
+compatibility_flags = ["nodejs_als"]
+\`\`\`
+
+Then run your dev command through the Meticulous CLI, which starts the sidecar and passes its URL to \`wrangler dev\`
+automatically:
+
+\`\`\`bash
+npx @alwaysmeticulous/cli record backend -- npx wrangler dev
+\`\`\`
+
+Authenticate with \`npx @alwaysmeticulous/cli auth login\` first (or pass \`--apiToken\`). If you prefer to run
+\`wrangler dev\` yourself, \`npx @alwaysmeticulous/cli record backend\` (without a wrapped command) starts just the
+sidecar and prints the \`--var METICULOUS_SIDECAR_URL:...\` / \`.dev.vars\` line to point your Worker at it — the value
+must be a worker var, since host environment variables are not visible inside workerd.
+
+\`fetch\` egress is captured (including \`node:http\`/\`node:https\` clients under \`nodejs_compat\`, which are implemented
+over fetch), as are calls through \`fetch\`-shaped bindings — service bindings and Durable Object stubs — with no code
+change beyond the \`withMeticulous\` wrapper. Assets bindings are skipped by default, since asset traffic is high-volume
+and adds nothing to a replay. KV, D1, R2, Queues, RPC method calls on a named entrypoint (\`env.SVC.someMethod()\`), and
+WebSockets are not yet supported.
+${BOOK_A_CALL_TIP}
+{% /tab %}
+
+{% /tabs %}
+
+## 3. Configuration options
+
+\`initBackendRecorder\` accepts an optional config object:
+
+| Option | Type | Description |
+|---|---|---|
+| \`enabled\` | \`boolean\` | Enable or disable the recorder. Defaults to \`true\`. |
+| \`meticulousProjectName\` | \`string\` | The name of your Meticulous project. |
+| \`recordingToken\` | \`string\` | Token used to authenticate span uploads. This is the same recording token used by the frontend recorder snippet. |
+| \`exportMode\` | \`"local" \\| "s3"\` | Where to export recorded spans. Defaults to \`"s3"\`, which uploads to Meticulous. Use \`"local"\` to write sessions to disk for debugging. |
+| \`localOutputDir\` | \`string\` | Directory for local exports. Only used when \`exportMode\` is \`"local"\`. |
+| \`flushIntervalMs\` | \`number\` | How often to flush spans, in milliseconds. |
+
+A common pattern is to record only in the environments you care about:
+
+{% code_with_project_selector %}
+\`\`\`ts
+await initBackendRecorder({
+  enabled: process.env.NODE_ENV !== "production",
+  meticulousProjectName: "{% project_name /%}",
+  recordingToken: "{% project_recording_token /%}",
+});
+\`\`\`
+{% /code_with_project_selector %}
+
+## 4. Flush spans on shutdown
+
+\`initBackendRecorder\` returns a handle with a \`stopRecording()\` method. Call it before your process exits so any pending spans are
+flushed and uploaded:
+
+\`\`\`ts
+const handle = await initBackendRecorder({
+  /* ...config... */
+});
+
+process.on("SIGTERM", async () => {
+  await handle?.stopRecording();
+  process.exit(0);
+});
+\`\`\`
+
+## 5. Recording anything else
+
+The recorder instruments the common clients automatically — \`fetch\`, \`http\`, Postgres, Prisma, Redis. For anything else, wrap the call
+yourself:
+
+\`\`\`ts
+const user = await handle.withMeticulousOperation(
+  { name: "crm.getUser", key: { id } },
+  () => crm.getUser(id),
+);
+\`\`\`
+
+While recording, Meticulous runs your function and captures what it returned. During a replay it does **not** run it — it returns the
+recorded result (or throws the recorded error) in its place. That is why the wrapper has to make the call rather than be told about it
+afterwards.
+
+There are two good reasons to reach for this.
+
+The first is a client we don't instrument — a gRPC stub, a vendor SDK with its own transport.
+
+The second is more interesting, and applies even to calls we *do* instrument: **an operation that sits above the network**. Take a
+function that checks an in-process cache and only calls an API on a miss. If the cache was warm while recording there was no request to
+record, so nothing is captured and the replay has nothing to serve. Wrap the function instead and the recording holds the operation
+itself — so it replays whether or not the cache happened to be warm, and cache hits stop making replays inconsistent.
+
+\`\`\`ts
+const getUser = (id: string) =>
+  handle.withMeticulousOperation({ name: "users.get", key: { id } }, async () => {
+    const cached = cache.get(id);
+    if (cached) return cached;
+    const user = await api.fetchUser(id);
+    cache.set(id, user);
+    return user;
+  });
+\`\`\`
+
+A few things to know:
+
+- **\`name\` identifies the operation, so renaming it invalidates existing recordings.** A test run compares against a base recorded days
+  or weeks earlier, so after a rename every call to that operation has nothing to match and the request fails. Rename deliberately.
+- **\`key\` is what distinguishes one call from another** — usually the arguments. Leave out values that change on every call but don't
+  affect the result, such as a request id or a nonce; including them means no call ever matches its recording. Timestamps and UUIDs are
+  handled for you, and if a key still doesn't match, Meticulous falls back to a recording of the same operation.
+- **Arguments and results are stored as JSON**, so a \`Date\` comes back as a string and a \`Map\` as \`{}\`. Meticulous logs a warning naming
+  the exact field when it sees one while recording. Thrown errors are captured and re-thrown with their \`name\`, \`message\` and custom
+  properties intact, though \`instanceof\` checks against your own error class won't match.
+- **Synchronous functions stay synchronous** on both paths.
+- **A call with no recording fails the request** rather than quietly running for real — a replay that reaches live services isn't
+  reproducible.
+
+To record app state that no call produces — resolved feature flags, a chosen experiment arm — use:
+
+\`\`\`ts
+handle.recordMeticulousObservation("featureFlags.resolved", flags);
+\`\`\`
+
+This only records: it never stubs anything, never throws, and is ignored during replay.
+
+### If you'd rather not hand us the call
+
+Some teams don't want their own code running inside our callback. The same capture is available as two calls you make yourself, with the
+branch in your code:
+
+\`\`\`ts
+function getUser(id: string) {
+  if (handle.isMeticulousReplaying()) {
+    return handle.stubWithMeticulous<User>(\`user_\${id}\`);
+  }
+
+  const user = crm.getUser(id);
+  handle.recordWithMeticulous(\`user_\${id}\`, user);
+
+  return user;
+}
+\`\`\`
+
+\`recordWithMeticulous\` takes the value the operation produced. A promise is fine, and is the usual case: its resolved value is recorded, the
+promise you return is untouched, and \`stubWithMeticulous\` then returns a promise to match. These are the same recordings
+\`withMeticulousOperation\` produces, so you can move between the two forms without invalidating anything. Here the name is the whole
+identity — there is no separate \`key\`, so put whatever distinguishes one call from another into the name.
+
+Use \`isMeticulousReplaying()\` for the branch rather than checking an env var yourself. The mode a process was started in, and an image
+built for Meticulous, are both the same in either mode, so neither tells you whether a recorded outcome can actually be served.
+
+Two things you give up by splitting it, which is why wrapping is still the better default where it's acceptable:
+
+- **A thrown error isn't captured.** \`recordWithMeticulous\` is handed a value, so a call that threw never reaches it and the replay has
+  nothing to serve. A rejected promise *is* captured. If failure is part of the flow, wrap instead.
+- **The branch is yours to get right**, and only the replay side of it is exercised by a replay — so a mistake in the other side won't
+  show up until it reaches production.
+
+That's it — once your app is running with the backend recorder enabled, server-side requests will be captured alongside the frontend
+sessions and used to stub backend calls during replay.
+`;

package/dist/commands/onboard/templates/docs/ci/not-yet-run-checks.ts

@@ -0,0 +1,58 @@
+import {
+  GITHUB_ACTIONS_SETUP_URL,
+  MAKE_CHECK_BLOCKING_URL,
+} from "src/lib/utils/internal-urls/docs-urls.utils";
+import { METICULOUS_GITHUB_CHECK_NAME } from "@alwaysmeticulous/webapp-frontend-backend-shared";
+import { INITIALIZE_WITH_SUCCESSFUL_CHECK_CHECKBOX_LABEL } from "src/components/project/overview/settings/ci-settings/not-yet-run-pull-request-commit-check.component";
+
+export const document = `---
+{
+  "title": "Create Meticulous check in 'success' state until tests start running"
+}
+---
+
+# {% $frontmatter.title %}
+
+In the default Meticulous setup you'll have a workflow that builds your app and invokes the
+[Meticulous GitHub Action](${GITHUB_ACTIONS_SETUP_URL}) (\`upload-assets\` or \`upload-container\` depending on how your app is served). Say you name this workflow '*trigger-meticulous-tests.yml*'. You can
+make Meticulous a blocking check by marking the '*${METICULOUS_GITHUB_CHECK_NAME}*' check as
+a [required check](${MAKE_CHECK_BLOCKING_URL}). The build process would therefore look like this:
+
+ 1. Your '*trigger-meticulous-tests.yml*' GitHub workflow is triggered (e.g. when a PR is opened). The '*${METICULOUS_GITHUB_CHECK_NAME}*' check
+    has not been created yet, since the Meticulous tests have not started yet, and since you've marked '*${METICULOUS_GITHUB_CHECK_NAME}*' as
+    a required check the PR will not be able to be merged yet.
+ 2. Once the build and pre-steps complete, the Meticulous action is invoked. This creates a second check on the PR, normally
+    named '*${METICULOUS_GITHUB_CHECK_NAME}*'. This check will show as pending until the tests complete. If there are unapproved differences it
+    will show as a failure, and will be updated to success when the differences are approved. Since you've marked the '*${METICULOUS_GITHUB_CHECK_NAME}*'
+    check as a required check, the PR will not be able to be merged until the differences are approved.
+ 3. Finally the '*trigger-meticulous-tests.yml*' workflow will complete, and be marked as success.
+
+{% callout type="warning" %}
+**Multiple projects for the same repository:** If you have more than one Meticulous project connected to the same GitHub repository (e.g. for testing different app variants or environments), the check name will include the project name — for example, *'Meticulous Tests (my-project)'* instead of *'${METICULOUS_GITHUB_CHECK_NAME}'*. Make sure your required status checks use the correct name. If you later add a second project to a repo that previously only had one, the check name will change and you'll need to update your branch protection rules accordingly.
+{% /callout %}
+
+However having the '*${METICULOUS_GITHUB_CHECK_NAME}*' check as a required check can cause issues in a couple of scenarios:
+
+ 1. If you use merge queues. In this case you don't want Meticulous to post a failed check if diffs are detected at the merge queue stage,
+    since that would block the merge queue from merging. Any differences should have already been approved before the PR was added to the
+    merge queue. It is therefore standard to skip the Meticulous workflow for merge queue triggers. However, if Meticulous is a
+    [required checks](${MAKE_CHECK_BLOCKING_URL}) then the merge queue would be indefinitely blocked because it'd be waiting for a check
+    that is never created.
+ 2. If you don't trigger Meticulous for every pull request. In this case you don't want to block merging PRs where Meticulous doesn't run
+    (i.e. no Meticulous check was ever created).
+
+There are two ways of solving these issues:
+
+ 1. Tick the '*${INITIALIZE_WITH_SUCCESSFUL_CHECK_CHECKBOX_LABEL}*' option in your Meticulous project settings.
+    This will cause Meticulous to register GitHub webhooks to monitor for new pull requests, new commit pushes, and for pull requests added
+    to merge queues. It will then create a successful '*${METICULOUS_GITHUB_CHECK_NAME}*' check in each of these cases straight away. This
+    check will start off as 'success' and turn to 'pending' when and if the Meticulous tests start running. If the Meticulous tests never run
+    then the check will be successful, and the PR can merge. This does however mean that developers will be able to merge pull requests in
+    the period between the PR being opened and the Meticulous tests being triggered after the build or deployment completes.
+ 2. Use a GitHub action such as [wait-for-checks](https://github.com/marketplace/actions/wait-for-checks) that only waits for checks that
+    are actually triggered, rather than waiting for a hard coded list of checks even if some of them are never triggered on some PRs. As long
+    as a GitHub workflow is running or a check pending while the application is being built prior to the Meticulous tests being triggered then
+    the PR will not be able to be merged until the tests complete. However if you trigger the Meticulous tests indirectly by creating a GitHub
+    deployment then there is a risk the PR will be mergeable in the handful of seconds between the workflow that creates the deployment completing
+    and Meticulous receiving the GitHub webhook for the new deployment and starting the tests.
+`;

package/dist/commands/onboard/templates/docs/ci.ts

@@ -0,0 +1,19 @@
+import {
+  CLOUD_REPLAY_URL,
+  GITHUB_ACTIONS_SETUP_URL,
+} from "src/lib/utils/internal-urls/docs-urls.utils";
+
+export const document = `---
+{
+  "title": "Setting up Meticulous to test your pull requests"
+}
+---
+
+# {% $frontmatter.title %}
+
+There are several ways to run Meticulous tests on your pull requests. We recommend the following approaches, in order of preference:
+
+1. **Upload static assets** — If your app can be served as a folder of static files (HTML/JS/CSS), this is the simplest approach. Not suitable for apps that require server-side rendering (e.g. Next.js). [Get started here](${GITHUB_ACTIONS_SETUP_URL}).
+2. **Upload a container image** — If your app requires a server (e.g. Next.js, SSR), upload a Docker image and we'll run it for you. This is the recommended approach for most apps. [Get started here](${GITHUB_ACTIONS_SETUP_URL}).
+3. **Use preview URLs** — If you already use Vercel, Netlify, or a similar service to generate PR preview URLs, Meticulous can test against those directly. [Learn more here](${CLOUD_REPLAY_URL}).
+`;

package/dist/commands/onboard/templates/docs/cloud-replay.ts

@@ -0,0 +1,145 @@
+import {
+  CREATE_DEPLOYMENTS_ON_GITHUB_URL,
+  GITHUB_ACTIONS_SETUP_URL,
+  MAKE_CHECK_BLOCKING_URL,
+} from "src/lib/utils/internal-urls/docs-urls.utils";
+import {
+  METICULOUS_GITHUB_APP_INSTALL_URL,
+  METICULOUS_VERCEL_INTEGRATION_INSTALL_URL,
+} from "./constants";
+import { linkGitLabInstructions } from "./how-to/link-gitlab";
+import { METICULOUS_SUPPORT_EMAIL } from "src/lib/next/next.constants";
+
+export const document = `---
+{
+  "title": "Running tests against existing deployment URLs"
+}
+---
+
+# {% $frontmatter.title %}
+
+{% callout_card variant="info" title="Preferred: Upload static assets or a container image" %}
+If possible, we recommend [running tests via your CI pipeline](${GITHUB_ACTIONS_SETUP_URL}) by uploading static assets or a container image. These approaches are simpler and more reliable. Use deployment URL testing only if those options are not possible for your app.
+{% /callout_card %}
+
+{% tabs %}
+{% tab label="GitHub" %}
+
+If you use Vercel, Netlify, Cloudflare Pages or a similar system to generate PR preview URLs you can use the Meticulous GitHub app to test your PRs for you:
+
+#### **Step 1: Install the Meticulous GitHub app**
+
+Begin by [installing the Meticulous GitHub app](${METICULOUS_GITHUB_APP_INSTALL_URL}).
+
+#### **Step 2: Integrate with your preview URL provider**
+
+Once the GitHub app is installed, select the system you use to generate PR preview links:
+
+{% tabs tabNameSpace="preview-provider" %}
+{% tab label="Vercel" %}
+
+Install the [Meticulous Vercel integration](${METICULOUS_VERCEL_INTEGRATION_INSTALL_URL}) and link your Vercel project in Meticulous.
+
+If you have multiple Vercel projects for your GitHub repo, or multiple environments that you deploy the same branches/commits to, then you'll
+need to let Meticulous know which environments it should run the tests against. You can do so by navigating to your project page and clicking on the *'Settings'* tab.
+
+{% /tab %}
+{% tab label="Netlify" %}
+
+If you use Netlify you can configure a Netlify webhook so tests are triggered when new preview deploys are ready. Contact
+[${METICULOUS_SUPPORT_EMAIL}](mailto:${METICULOUS_SUPPORT_EMAIL}) for help setting this up.
+
+{% /tab %}
+{% tab label="Cloudflare" %}
+
+If you use Cloudflare pages you can configure a Cloudflare webhook so tests are triggered when new preview deploys are ready. Contact
+[${METICULOUS_SUPPORT_EMAIL}](mailto:${METICULOUS_SUPPORT_EMAIL}) for help setting this up.
+
+{% /tab %}
+{% tab label="Other/Home-Grown" %}
+
+If you use another preview URL system, or a home grown system you can generate
+a GitHub deployment (environment) whenever a commit is pushed to a branch. This can then in turn be used to trigger a Meticulous test run
+against the new deployment.
+
+You can view instructions for how to do this [here](${CREATE_DEPLOYMENTS_ON_GITHUB_URL}), however it can be
+fragile to set up correctly, and requires your PR preview system to have immutable, long-lived preview URLs and use identical
+build settings across PR branches and main branch commits (to avoid false screenshot diffs). For this reason we recommend
+[triggering Meticulous from your CI pipeline instead](${GITHUB_ACTIONS_SETUP_URL}), if possible.
+
+{% /tab %}
+{% /tabs %}
+
+#### **Step 3 (optional): Make the Meticulous check blocking**
+
+Whenever you open a new pull request Meticulous will now simulate a set of sessions against the preview URL before and after the PR, and post
+a comment to the PR notifying of any changes spotted.
+
+If you wish, you can make this check blocking by following the instructions [here](${MAKE_CHECK_BLOCKING_URL}). Doing so will prevent developers
+from merging a PR which has visual differences until they have clicked the button to acknowledge the differences.
+
+{% /tab %}
+{% tab label="GitLab" %}
+
+## Initial setup
+
+If you use Vercel, Netlify or a similar system to generate PR preview URLs, you can use Meticulous to test your PRs.
+To set this up:
+
+${linkGitLabInstructions}
+
+## Further steps
+
+{% tabs %}
+{% tab label="Vercel" %}
+
+Please let us know that you are using Vercel preview URLs in the email you sent us when setting up GitLab.
+After some setup on our side Meticulous will automatically run tests against Vercel preview URLs whenever a new deployment is ready.
+
+{% /tab %}
+{% tab label="Other preview URL providers" %}
+
+Call the */test-runs/trigger* endpoint from your GitLab CI pipeline whenever a new commit is pushed to a branch with an open MR.
+The endpoint will trigger a test run, and Meticulous will handle setting commit statuses and posting notes to the merge request as
+the test run progresses.
+
+{% code_with_project_selector %}
+\`\`\`http
+POST https://app.meticulous.ai/api/test-runs/trigger
+
+Headers: {
+  authorization: "{% api_token /%}"
+  Content-Type: "application/json"
+}
+
+Body: {
+  headSha: string, // the SHA of the commit you want to test
+  headDeploymentUrl: string, // preview URL of headSha
+  baseSha: string, // the SHA of the commit which the new test run will be compared against
+  baseDeploymentUrl: string // preview URL of baseSha
+}
+\`\`\`
+{% /code_with_project_selector %}
+
+There are two different types of pipelines that GitLab can trigger when a new commit is pushed to a branch with an open MR: *merge request
+pipelines* and *merged results pipelines* ([GitLab docs](https://docs.gitlab.com/ee/ci/pipelines/merged_results_pipelines.html)). Your
+pipeline should call the */test-runs/trigger* endpoint with different values for \`headSha\` and \`baseSha\` depending on which type of
+pipeline you use.
+
+If you use merge request pipelines:
+- \`headSha\` should be the SHA of the commit that was just pushed to the branch. This is exposed in the CI pipeline as
+\`$CI_COMMIT_SHA\`.
+- \`baseSha\` should be the SHA of the commit from which the branch was created. This is exposed in the CI pipeline as
+\`$CI_MERGE_REQUEST_DIFF_BASE_SHA\`.
+
+If you use merged results pipelines:
+- \`headSha\` should be the SHA of the merge commit. This is exposed in the CI pipeline as \`$CI_COMMIT_SHA\`.
+- \`baseSha\` should be the SHA of the HEAD commit on the target branch. This is exposed in the CI pipeline as
+\`$CI_MERGE_REQUEST_TARGET_BRANCH_SHA\`.
+
+{% /tab %}
+{% /tabs %}
+
+{% /tab %}
+{% /tabs %}
+`;

package/dist/commands/onboard/templates/docs/constants.ts

@@ -0,0 +1,37 @@
+import { METICULOUS_SUPPORT_EMAIL } from "src/lib/next/next.constants";
+
+export const METICULOUS_VERCEL_INTEGRATION_INSTALL_URL =
+  "https://vercel.com/integrations/meticulous";
+
+export const METICULOUS_GITHUB_APP_INSTALL_URL =
+  "https://github.com/apps/alwaysmeticulous/installations/new";
+
+export const WHERE_CAN_I_REACH_OUT_FOR_SUPPORT = `
+  ### Where can I reach out for support?
+
+  Reach out to [${METICULOUS_SUPPORT_EMAIL}](mailto:${METICULOUS_SUPPORT_EMAIL}) and we'll be happy to help.
+  `;
+
+export const METICULOUS_DEBUG_PR_LABEL = "[meticulous debug]";
+
+export const SIMULATION_TAB_NAMES = {
+  DEBUG_LOCALLY: "Debug Locally",
+  TIMELINE_AND_LOGS: "Timeline & Logs",
+};
+
+/**
+ * Keep in sync with [@alwaysmeticulous/browser-utils](https://github.com/alwaysmeticulous/meticulous/blob/9c89cf58ae240bea0f9201c5d704a0bcc53e61bd/packages/browser-utils/src/utils/public-api-classes.ts#L11).
+ */
+export const METICULOUS_REDACT_RECORDING_CLASS = "meticulous-redact-recording";
+
+/**
+ * Keep in sync with [@alwaysmeticulous/browser-utils](https://github.com/alwaysmeticulous/meticulous/blob/9c89cf58ae240bea0f9201c5d704a0bcc53e61bd/packages/browser-utils/src/utils/public-api-classes.ts#L11).
+ */
+export const METICULOUS_MASK_RECORDING_PREVIEW_CLASS =
+  "meticulous-mask-recording-preview";
+
+export const GITHUB_ACTION_UPLOAD_ASSETS_NAME =
+  "alwaysmeticulous/report-diffs-action/upload-assets";
+
+export const GITHUB_ACTION_UPLOAD_CONTAINER_NAME =
+  "alwaysmeticulous/report-diffs-action/upload-container";