@alwaysmeticulous/cli 2.331.3 → 2.332.0

package/dist/commands/onboard/templates/docs/github-actions-v2.ts

@@ -1,9 +1,9 @@
 import { METICULOUS_SUPPORT_EMAIL } from "src/lib/next/next.constants";
 import {
   BRANCHES_REQUIRED_TO_RUN_ON_URL,
-  CLOUD_REPLAY_URL,
   ENABLE_SOURCE_COVERAGE_URL,
   MAKE_CHECK_BLOCKING_URL,
+  ONBOARDING_GUIDE_URL,
 } from "src/lib/utils/internal-urls/docs-urls.utils";
 import {
   GITHUB_ACTION_UPLOAD_ASSETS_NAME,
@@ -44,8 +44,14 @@ on:
   pull_request: {}
   # Important: We need the workflow to be triggered on workflow_dispatch events,
   # so that Meticulous can run the workflow on the base commit to compare
-  # against if an existing workflow hasn't run
-  workflow_dispatch: {}`;
+  # against if an existing workflow hasn't run. The meticulous-commit-sha input
+  # lets Meticulous ask for a specific commit (e.g. stacked PRs); without it,
+  # a dispatched run can only build whatever the branch currently points at.
+  workflow_dispatch:
+    inputs:
+      meticulous-commit-sha:
+        description: Commit Meticulous has asked this run to build. Defaults to the branch head.
+        required: false`;
 
 const workflowShared = `
 name: Meticulous
@@ -61,6 +67,11 @@ permissions:
   pull-requests: write
   statuses: read
 
+env:
+  # Prefer the dispatched commit when set; otherwise the PR head. On pull_request github.sha is the merge commit,
+  # not the PR head SHA that Meticulous looks up.
+  METICULOUS_COMMIT_SHA: \${{ github.event.inputs['meticulous-commit-sha'] || (github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha) }}
+
 jobs:
   test:
     name: Meticulous
@@ -69,6 +80,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          ref: \${{ env.METICULOUS_COMMIT_SHA }}
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -95,29 +108,13 @@ jobs:
           pnpm install --frozen-lockfile
 
       - name: Build project
-        # METICULOUS_BUILD marks this as a build for Meticulous testing (see note above).
+        # METICULOUS_BUILD marks this as a build for Meticulous testing.
         env:
           METICULOUS_BUILD: "true"
         run: |
           pnpm build
 `;
 
-const meticulousBuildEnvNote = `
-{% callout_card variant="info" title="The METICULOUS_BUILD environment variable" %}
-The example workflows below set \`METICULOUS_BUILD=true\` on the build (and, for container
-builds, on the image). This marks the build as one that Meticulous will test, so your app can
-detect it and adjust behaviour that would otherwise be unreliable during replay — most
-commonly **skipping retry-heavy data fetches** in server-side lifecycle hooks
-(\`getServerSideProps\`, \`getInitialProps\`, loaders) that have no recorded response during
-replay and would otherwise fail and be retried repeatedly.
-
-Because it is set **only** in your Meticulous build (never in production), it is safe to gate
-behaviour on — unlike a request header, it cannot be spoofed. In server / build-time code read
-it with \`process.env.METICULOUS_BUILD === "true"\`; in browser code prefer
-\`window.Meticulous?.isRunningAsTest\`. If your app does not need it, leaving it set is harmless.
-{% /callout_card %}
-`;
-
 export const document = `---
 {
   "title": "Setting up Meticulous tests to run in your CI provider"
@@ -133,7 +130,7 @@ In this guide, we'll show you how to set up Meticulous to run in your CI system.
 
 ## 1. Install the Meticulous GitHub App
 
-Visit [${METICULOUS_GITHUB_APP_INSTALL_URL}](${METICULOUS_GITHUB_APP_INSTALL_URL}) to install our GitHub App.
+If you haven't already connected this repository in [Connect your repository](${ONBOARDING_GUIDE_URL}#1-connect-your-repository), visit [${METICULOUS_GITHUB_APP_INSTALL_URL}](${METICULOUS_GITHUB_APP_INSTALL_URL}) to install our GitHub App.
 
 ## 2. Add your Meticulous API token as a secret to your GitHub repository
 
@@ -176,12 +173,6 @@ We offer two approaches to running Meticulous tests on CI. We recommend choosing
 1. **Upload your built assets** for us to test. This is the recommended approach if your app is a static site, i.e. it can be served as a folder of static assets (HTML/JS/CSS) without any server-side rendering or complex request rewriting. This approach is **NOT recommended** for Next.js applications as they typically cannot be served as static assets.
 2. **Upload a built container image** (e.g. a Docker image) for us to test. This is the recommended approach for most other apps, including Next.js applications. Almost any app can be containerized, so this is the universal fallback.
 
-{% callout_card variant="info" title="Recommended approaches" %}
-We recommend **uploading static assets** or **uploading a container image**. These are the simplest and most reliable ways to run Meticulous tests.
-
-If you use a preview URL provider such as Vercel, Netlify, or similar, Meticulous can also test your PRs using [cloud replay](${CLOUD_REPLAY_URL}). Uploading static assets or a container image are still the preferred approaches.
-{% /callout_card %}
-${meticulousBuildEnvNote}
 {% tabs tabNameSpace="type" %}
 {% tab label="Upload static assets" %}
 
@@ -235,9 +226,9 @@ ${workflowShared}
         uses: docker/build-push-action@v6
         with:
           context: .
-          tags: my-app:\${{ github.sha }}
+          tags: my-app:\${{ env.METICULOUS_COMMIT_SHA }}
           push: false
-          # Marks the image as a Meticulous build (see note above). Consume it in your
+          # Marks the image as a Meticulous build. Consume it in your
           # Dockerfile with \`ARG METICULOUS_BUILD\` / \`ENV METICULOUS_BUILD=$METICULOUS_BUILD\`
           # if you need it at build time (e.g. getStaticProps / static generation).
           build-args: |
@@ -247,11 +238,11 @@ ${workflowShared}
         uses: ${GITHUB_ACTION_UPLOAD_CONTAINER_NAME}@v1
         with:
           api-token: \${{ secrets.METICULOUS_API_TOKEN }}
-          image-tag: my-app:\${{ github.sha }}
+          image-tag: my-app:\${{ env.METICULOUS_COMMIT_SHA }}
           # Optional inputs:
           container-port: 1234
           # METICULOUS_BUILD is also passed at runtime so server-side code (e.g.
-          # getServerSideProps) can detect the Meticulous replay. See note above.
+          # getServerSideProps) can detect the Meticulous replay.
           container-env: |
             MY_ENV_VAR=my-value
             METICULOUS_BUILD=true
@@ -319,7 +310,11 @@ on:
     paths:
       - "apps/dashboard/**"
       - "packages/ui/**"
-  workflow_dispatch: {}
+  workflow_dispatch:
+    inputs:
+      meticulous-commit-sha:
+        description: Commit Meticulous has asked this run to build. Defaults to the branch head.
+        required: false
 
 permissions:
   actions: write
@@ -328,6 +323,11 @@ permissions:
   pull-requests: write
   statuses: read
 
+env:
+  # Prefer the dispatched commit when set; otherwise the PR head. On pull_request github.sha is the merge commit,
+  # not the PR head SHA that Meticulous looks up.
+  METICULOUS_COMMIT_SHA: \${{ github.event.inputs['meticulous-commit-sha'] || (github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha) }}
+
 jobs:
   test:
     name: Meticulous (dashboard)
@@ -335,6 +335,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: \${{ env.METICULOUS_COMMIT_SHA }}
       - uses: actions/setup-node@v4
         with:
           node-version: "24"
@@ -510,6 +512,8 @@ then you can use our \`ci upload-assets\` CLI command to upload your built asset
 
 ## 1. Link GitLab to Meticulous
 
+If you haven't already connected this repository in [Connect your repository](${ONBOARDING_GUIDE_URL}#1-connect-your-repository), complete the steps below.
+
 ${linkGitLabInstructions}
 
 ## 2. Add your Meticulous API token as a CI/CD variable
@@ -529,7 +533,7 @@ METICULOUS_API_TOKEN:
 To run Meticulous on CI, add a new \`.gitlab-ci.yml\` file to your repository. The pipeline needs to run on both pushes to your main branch and on merge requests.
 
 This pipeline should use our \`ci upload-assets\` CLI command to upload your built assets for us to test.
-${meticulousBuildEnvNote}
+
 File name: \`.gitlab-ci.yml\`
 
 File contents:
@@ -545,7 +549,7 @@ variables:
 build:
   stage: build
   image: node:24-alpine
-  # METICULOUS_BUILD marks this as a build for Meticulous testing (see note above).
+  # METICULOUS_BUILD marks this as a build for Meticulous testing.
   variables:
     METICULOUS_BUILD: "true"
   script:
@@ -781,6 +785,8 @@ then you can use our \`ci upload-assets\` CLI command to upload your built asset
 
 ## 1. Link Bitbucket to Meticulous
 
+If you haven't already connected this repository in [Connect your repository](${ONBOARDING_GUIDE_URL}#1-connect-your-repository), complete the steps below.
+
 ${linkBitbucketInstructions}
 
 ## 2. Add your Meticulous API token as a repository variable
@@ -800,7 +806,7 @@ METICULOUS_API_TOKEN:
 To run Meticulous on CI, add a \`bitbucket-pipelines.yml\` file to your repository. The pipeline needs to run on both pushes to your main branch and on pull requests.
 
 This pipeline should use our \`ci upload-assets\` CLI command to upload your built assets for us to test.
-${meticulousBuildEnvNote}
+
 On pull request builds, Bitbucket merges the destination branch into the source branch during **Build Setup** before your steps run. Meticulous does **not** support testing that ephemeral merge commit. **Checkout the PR source tip** before building so uploads use a commit Bitbucket exposes via the API and the backend can compare against the **merge-base** with the destination branch.
 
 Add this step at the start of your pull-request pipeline script:
@@ -827,7 +833,7 @@ pipelines:
             - node
           script:
             - npm ci
-            # METICULOUS_BUILD marks this as a build for Meticulous testing (see note above).
+            # METICULOUS_BUILD marks this as a build for Meticulous testing.
             - METICULOUS_BUILD=true npm run build
             - >
               npx @alwaysmeticulous/cli ci upload-assets
@@ -843,7 +849,7 @@ pipelines:
           script:
             - git reset --hard "$BITBUCKET_COMMIT"
             - npm ci
-            # METICULOUS_BUILD marks this as a build for Meticulous testing (see note above).
+            # METICULOUS_BUILD marks this as a build for Meticulous testing.
             - METICULOUS_BUILD=true npm run build
             - >
               npx @alwaysmeticulous/cli ci upload-assets

package/dist/commands/onboard/templates/docs/how-to/connect-git-provider.ts

@@ -0,0 +1,26 @@
+import { METICULOUS_GITHUB_APP_INSTALL_URL } from "../constants";
+import { linkBitbucketInstructions } from "./link-bitbucket";
+import { linkGitLabInstructions } from "./link-gitlab";
+
+export const connectGitProviderInstructions = `
+{% tabs tabNameSpace="provider" %}
+{% tab label="GitHub" %}
+
+1. Sign in to [Meticulous](https://app.meticulous.ai) and create or select your organization.
+2. Choose **Connect to GitHub** when creating the project.
+3. [Install the Meticulous GitHub App](${METICULOUS_GITHUB_APP_INSTALL_URL}) for the organization and repositories you want Meticulous to test.
+4. Return to Meticulous, select the repository, and create the linked project.
+
+{% /tab %}
+{% tab label="GitLab" %}
+
+${linkGitLabInstructions}
+
+{% /tab %}
+{% tab label="Bitbucket" %}
+
+${linkBitbucketInstructions}
+
+{% /tab %}
+{% /tabs %}
+`;

package/dist/commands/onboard/templates/docs/how-to/typescript-types.ts

@@ -13,7 +13,7 @@ TypeScript definitions for the \`window.Meticulous\` object are available in the
 Install the package as a dev dependency:
 
 \`\`\`bash
-npm install --save-dev @alwaysmeticulous/sdk-bundles-api
+npm install --save-dev @alwaysmeticulous/sdk-bundles-api@latest
 \`\`\`
 
 ## Usage