feat(providers): add providerMeta (#59)

[theoephraim]

Closes #59 (partially — the git/build metadata half).

Obviously feel free to adapt as necessary. The important parts (all the provider specific detection and vars) should be easy to reuse however you see fit.

This comes from well worn code in varlock - although I highly doubt we've had users on all the more obscure providers.

---

What

Adds detectProviderMetadata() / providerMetadata, exposing normalized git and build metadata for the detected CI/CD or deployment provider:

import { providerMetadata } from "std-env";
// {
//   name: "github_actions",
//   repo: { owner: "unjs", name: "std-env" },
//   repoSlug: "unjs/std-env",
//   branch: "main",
//   commitSha: "abcdef1234567890...",
//   commitShaShort: "abcdef1",
//   isPR: false,
//   runId: "42",
//   buildUrl: "https://github.com/unjs/std-env/actions/runs/42",
//   actor: "octocat",
//   eventName: "push",
// }

Fields: name, repo {owner,name}, repoSlug, branch, commitSha, commitShaShort, isPR, prNumber, environment, buildUrl, runId, actor, eventName, workflowName. All optional except name — availability depends on the provider and event.

The extraction logic and per-provider env var mappings are adapted from @varlock/ci-env-info. It shows no npm downloads because while it is usable on its own, it's an internal package that ships inside Varlock, where this metadata powers builtin variables and is used to automatically infer the current environment (production / preview / development) from the CI/deploy context. So the mappings here are already battle-tested across real CI providers, not net-new.

Design notes

• Separate module (src/provider-metadata.ts), out of the detection hot path. providers.ts stays free of per-provider extractor closures, so importing only isCI/provider doesn't pull in the metadata engine. Verified with esbuild — a { isCI, provider } bundle contains zero metadata extractors; the module is side-effect-free (Side effects: 0 B).
• Single source of truth for detection. detectProviderMetadata() calls the existing detectProvider() for the provider name, then looks up extractors in a Partial<Record<ProviderName, ProviderExtractors>> keyed by the same lowercase names. No parallel detection list.
• Honors project conventions: env proxy (no bare process), lazy /* #__PURE__ */ singleton, .ts imports.
• ~20 providers with git/build metadata included (all the ones std-env already detects that expose it: GitHub Actions, GitLab, Vercel, Netlify, Cloudflare Pages/Workers, CircleCI, Travis, Buildkite, Bitbucket, Azure Pipelines, CodeBuild, Drone, Render, Semaphore, AppVeyor, Bitrise, Cirrus, Codefresh, Jenkins). Providers without metadata just return { name }.

Open questions for review

• Naming. Went with providerMetadata/detectProviderMetadata alongside providerInfo. Happy to rename or reshape — e.g. folding into providerInfo, though that reintroduces the tree-shaking cost the split avoids.
• Shape. Dropped docsUrl/raw/isCI from the upstream varlock shape (std-env already has isCI; the others felt out of scope). Easy to add back.

Checklist

• pnpm lint / pnpm typecheck / pnpm test pass (8 new tests)
• pnpm build succeeds; new exports present in dist
• README + AGENTS.md updated

Summary by CodeRabbit

• New Features
  • Added CI/CD “Provider Metadata” detection with a normalized metadata object (repo, branch, PR details, commit SHA, environment, actor, event, workflow, and build/run info).
  • Exposed new metadata exports, including providerMetadata and detectProviderMetadata.
• Documentation
  • Documented Provider Metadata in the README and updated AGENTS guidance with structured Source Structure and metadata module details.
• Tests
  • Added/expanded Vitest coverage for provider metadata extraction across multiple CI/CD platforms and scenarios.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR adds a new provider metadata module, exports it from the package entrypoint, documents the API, and adds tests for provider-specific metadata extraction.

Changes

Provider Metadata Feature

Layer / File(s)	Summary
Type declarations and extractor registry src/provider-metadata.ts	Declares the normalized metadata types and the provider-keyed extractor registry for metadata fields.
Core detectProviderMetadata implementation src/provider-metadata.ts	Builds normalized metadata from detectProvider() and provider-specific extractors, and exports the eager providerMetadata value.
Parsing and normalization helpers src/provider-metadata.ts	Adds helpers for environment resolution, branch cleanup, repo slug parsing, PR number parsing, and environment mapping.
Public exports and documentation src/index.ts, README.md, AGENTS.md	Re-exports the new API and documents the metadata shape plus source-structure guidance.
Provider metadata test suite test/provider-metadata.test.ts	Covers detection and extraction behavior for the supported CI providers and the default case.

Estimated code review effort: 3 (Moderate) | ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR adds normalized metadata extraction and exports for the requested CI/CD providers and fields in #59.
Out of Scope Changes check	✅ Passed	The changes stay focused on metadata extraction, exports, tests, and docs with no clear unrelated additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and points to the new provider metadata API, even though it uses a shortened name.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

test/provider-metadata.test.ts (1)

62-85: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider adding a workflowName assertion to the GitHub Actions push test.

GITHUB_WORKFLOW is listed in envKeys (line 17) and workflowName is a documented metadata field, but no test asserts it. Adding a stub and assertion to the existing GitHub Actions push test would close this coverage gap with minimal effort.

🧪 Suggested addition

     vi.stubEnv("GITHUB_ACTOR", "octocat");
+    vi.stubEnv("GITHUB_WORKFLOW", "CI");
 
     expect(detectProviderMetadata()).toMatchObject({
       name: "github_actions",
       repo: { owner: "unjs", name: "std-env" },
       repoSlug: "unjs/std-env",
       branch: "main",
       commitSha: "abcdef1234567890",
       commitShaShort: "abcdef1",
       isPR: false,
       runId: "42",
       buildUrl: "https://github.com/unjs/std-env/actions/runs/42",
       actor: "octocat",
       eventName: "push",
+      workflowName: "CI",
     });

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/provider-metadata.test.ts` around lines 62 - 85, The GitHub Actions push
metadata test in detectProviderMetadata is missing coverage for the documented
workflowName field even though GITHUB_WORKFLOW is included in envKeys. Update
the existing GitHub Actions push case to stub GITHUB_WORKFLOW and assert the
returned metadata includes workflowName, using detectProviderMetadata and the
same toMatchObject block so the coverage stays aligned with the other GitHub
Actions fields.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/provider-metadata.ts`:
- Line 162: The buildUrl mapping in the provider metadata is double-prefixing
Netlify deploy URLs with https://, which produces invalid URLs. Update the
buildUrl handler in provider-metadata to use env.DEPLOY_URL directly when it is
present, and keep the undefined fallback unchanged so Netlify’s already
fully-qualified URL is returned as-is.
- Around line 142-143: The GitLab merge-request number mapping in provider
metadata is using the instance-wide ID instead of the user-facing MR IID. Update
the `provider-metadata` mapping for `prNumber` to use `CI_MERGE_REQUEST_IID`
while keeping `isPR` unchanged unless you intentionally want to align it too;
the relevant symbols to adjust are the merge-request fields in the provider
metadata object.
- Line 128: The prNumber resolver in provider metadata is reading the wrong
GitHub Actions variable, so PR builds never resolve a number. Update the
prNumber mapping in the provider-metadata logic to use env.GITHUB_REF with
parsePrNumber, since that helper already understands the pull ref format; keep
the change localized to the prNumber callback and ensure no other callers still
rely on GITHUB_EVENT_NUMBER.

In `@test/provider-metadata.test.ts`:
- Around line 116-130: Handle Netlify DEPLOY_URL values without double-prefixing
the scheme. In detectProviderMetadata, update the Netlify URL normalization so
the buildUrl logic checks whether DEPLOY_URL already starts with https:// before
prepending it; only add the scheme when it is missing. Keep the behavior covered
by the existing provider metadata test for the Netlify deploy-preview case.

---

Nitpick comments:
In `@test/provider-metadata.test.ts`:
- Around line 62-85: The GitHub Actions push metadata test in
detectProviderMetadata is missing coverage for the documented workflowName field
even though GITHUB_WORKFLOW is included in envKeys. Update the existing GitHub
Actions push case to stub GITHUB_WORKFLOW and assert the returned metadata
includes workflowName, using detectProviderMetadata and the same toMatchObject
block so the coverage stays aligned with the other GitHub Actions fields.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: aba0544a-432e-43b4-a65f-1011a240b56a

📥 Commits

Reviewing files that changed from the base of the PR and between 7b6b8b1 and d11beb6.

📒 Files selected for processing (5)

• AGENTS.md
• README.md
• src/index.ts
• src/provider-metadata.ts
• test/provider-metadata.test.ts

[theoephraim]

Pushed fixes for the review, plus an independent audit of every provider's env vars against official docs.

From the CodeRabbit review

• GitHub prNumber — GITHUB_EVENT_NUMBER doesn't exist; parse from GITHUB_REF (refs/pull/<n>/merge), but gated on refs/pull/ so branch names ending in digits aren't mistaken for PR numbers.
• GitLab prNumber — switched to CI_MERGE_REQUEST_IID (user-facing MR number) instead of the instance-wide CI_MERGE_REQUEST_ID.
• Netlify buildUrl — DEPLOY_URL is already fully-qualified https://, so the https://${…} prefix produced https://https://…. Now used verbatim.
• Added workflowName test coverage.

From the docs audit (beyond the bot's findings)

• Azure prNumber — SYSTEM_PULLREQUEST_PULLREQUESTID is Azure's internal id for GitHub-based PRs; prefer SYSTEM_PULLREQUEST_PULLREQUESTNUMBER, falling back to the id (they coincide for Azure Repos).
• Bitbucket repo owner — BITBUCKET_REPO_OWNER is deprecated → BITBUCKET_WORKSPACE.
• Semaphore prNumber — PULL_REQUEST_NUMBER doesn't exist on Semaphore 2.0; corrected to SEMAPHORE_GIT_PR_NUMBER.
• GitHub branch — prefer the documented short GITHUB_REF_NAME before hand-parsing the ref.
• Bitrise — added repo extraction via BITRISEIO_GIT_REPOSITORY_OWNER/_SLUG.

Known, documented caveat

For Travis / AppVeyor / Semaphore, on PR builds the branch field is the target branch (what the PR merges into), not the source — noted inline. Happy to add a sourceBranch/baseBranch split if you'd prefer; left it out to keep the shape lean for now.

Confirmed correct and unchanged: Vercel (VERCEL_URL has no scheme, so its https:// prefix is right), Cloudflare Pages/Workers, CircleCI, Buildkite, Drone, Codefresh, Cirrus (CIRRUS_CHANGE_IN_REPO is the commit SHA), CodeBuild, Render.

All green: 33 tests, typecheck, lint, build. Still a draft pending direction on naming/shape.