chore: improve codex agent setup

[hassiebp]

Summary

• Add a root AGENTS.md with repo-specific guidance for Codex and other coding agents.
• Add Codex setup and maintenance scripts that pin pnpm via Corepack and prepare the repo for dist-backed tests.
• Codify shared Langfuse contribution conventions: Conventional Commit PR titles, verification commands in the PR template, and agent-local artifact ignores.
• Add semantic PR title validation and fix an existing pnpm typecheck issue in media upload headers.

Why

The repo did not have Codex-readable project guidance or deterministic cloud setup commands. Some documented commands also did not exist. This PR makes the repo easier for agents to enter, validate, and publish changes consistently.

Verification

• bash -n scripts/codex/setup.sh scripts/codex/maintenance.sh
• pnpm format:check
• pnpm lint
• pnpm typecheck
• pnpm test:integration
• git diff --check
• Husky precommit: turbo run check:lint check:type check:format --continue=never

Disclaimer: Experimental PR review

Greptile Summary

This PR improves the developer and agent experience for the langfuse-js monorepo by adding AGENTS.md, Codex setup/maintenance scripts, a PR title validation workflow, and several documentation updates. It also includes a small TypeScript type fix in MediaService.ts that adds an explicit Record<string, string> annotation to the headers variable to resolve a typecheck failure.

Confidence Score: 5/5

This PR is safe to merge; all changes are additive documentation, scripts, and a minor type annotation fix.

Only one P2 style observation (test:integration:watch triggers a full build on every watch start). No logic bugs, security issues, or breaking changes were found.

No files require special attention.

Important Files Changed

Filename	Overview
.github/pull_request_template.md	Adds Verification checklist section and corrects package names in the sub-libraries list; no issues.
.github/workflows/validate-pr-title.yml	New workflow pinned to a SHA for security, least-privilege permissions at job level; straightforward and correct.
.gitignore	Adds agent-local artifact ignores (.codex/, .mcp.json, .playwright-mcp/); no issues.
AGENTS.md	New repo-level guide for Codex agents; commands and package boundaries match the repo; no issues.
CONTRIBUTING.md	Updates prerequisites, adds Codex cloud setup instructions and Conventional Commits guidance; no issues.
package.json	Adds test:integration:watch (triggers full build on every watch start) and release:dry; otherwise clean.
packages/otel/src/MediaService.ts	Adds explicit Record<string, string> annotation to headers to satisfy TypeScript; correct fix.
scripts/codex/setup.sh	Setup script with Corepack pnpm pin, .env bootstrapping, install, and build; logic is correct.
scripts/codex/maintenance.sh	Maintenance script that re-enables Corepack and runs frozen install; intentionally omits build step.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Codex Agent Starts] --> B{corepack available?}
    B -- No --> C[Exit with error]
    B -- Yes --> D[corepack enable\ncorepack prepare pnpm@10.33.0]
    D --> E{Running setup\nor maintenance?}
    E -- setup --> F[ensure_env_file\n.env from .env.example]
    F --> G[pnpm install --frozen-lockfile]
    G --> H[pnpm build]
    H --> I[Agent ready for\nintegration & e2e tests]
    E -- maintenance --> J[pnpm install --frozen-lockfile]
    J --> I

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: package.json
Line: 19

Comment:
**`test:integration:watch` always triggers a full build**

Every invocation of the watch mode runs `pnpm run build` before starting the Vitest watcher. This is consistent with the non-watch counterpart, but in a watch loop the build only needs to happen once. Repeated watch restarts (e.g. after a crash) will each trigger a full rebuild. Consider documenting that callers should run `pnpm build` manually first and then invoke a bare `vitest --project=integration`, or accept the current behaviour as intentional.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "Merge branch 'main' into codex/improve-c..." | Re-trigger Greptile}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-js	Ready	Preview	Apr 27, 2026 5:55am

[github-actions]

@claude review

[claude]

LGTM — agent tooling, docs, and CI config plus a one-line type annotation fix; the flagged watch-mode ergonomics nit is non-blocking.

Extended reasoning...

Overview

This PR is overwhelmingly non-code: a new AGENTS.md for coding-agent guidance, Codex setup.sh/maintenance.sh shell scripts that pin pnpm via Corepack and prebuild dist artifacts, an updated PR template, expanded CONTRIBUTING.md, additional .gitignore entries for agent-local files, and a new validate-pr-title.yml workflow that uses amannn/action-semantic-pull-request (pinned to an immutable SHA, with minimal statuses: write / pull-requests: read permissions). package.json adds test:integration:watch and release:dry npm scripts. The only source change is a one-line type annotation (headers: Record<string, string>) in packages/otel/src/MediaService.ts that fixes a tsc issue without altering runtime behavior.

Security risks

Minimal. The new GitHub Actions workflow uses a SHA-pinned third-party action with narrowly scoped permissions, and the Codex shell scripts run set -euo pipefail, gate on corepack availability, and only invoke corepack enable, corepack prepare, pnpm install --frozen-lockfile, and pnpm build — no curl-piping, no secret handling, no destructive operations. ensure_env_file only copies .env.example to .env if neither file exists, which is safe. No auth, crypto, or permissions code is touched.

Level of scrutiny

Low. This is contributor-experience and CI tooling plus a single trivial type fix. None of it touches public SDK APIs, network code paths, persistence, or release/publishing logic in a behavior-changing way (the new release:dry script is purely additive and uses release-it's built-in --dry-run).

Other factors

The only bug found by the hunting system is a Nit about test:integration:watch not auto-rebuilding on source edits — a real but minor developer-ergonomics issue with an obvious workaround, not a correctness or security concern. No outstanding reviewer comments, no CODEOWNER-sensitive paths, and the author has self-listed verification commands in the PR description.

[claude]

🟡 The new test:integration:watch script chains pnpm run build && vitest --project=integration, so the build runs only once at startup. Because the integration project aliases @langfuse/* to ./packages/*/dist/index.mjs (vitest.workspace.ts:13-37), edits to packages/*/src/*.ts won't trigger a rebuild and tests will silently keep running against stale dist artifacts. Watch mode still works for editing tests under tests/integration/**, but iterating on SDK source — the most natural use of :watch — requires a parallel pnpm -r build --watch (worth either documenting or wiring into the script via something like concurrently).

Extended reasoning...

What the bug is. package.json:19 adds "test:integration:watch": "pnpm run build && vitest --project=integration". The two commands are shell-chained with &&, so pnpm run build executes exactly once at script startup. Vitest then enters watch mode. The integration project's vitest config aliases all @langfuse/* imports to the prebuilt ./packages/*/dist/index.mjs files (vitest.workspace.ts:13-37), so the file watcher follows the resolved dist/index.mjs outputs, not the original packages/*/src/*.ts sources.\n\nHow it manifests. Integration tests use the dist outputs by design, so a developer iterating on SDK behavior under watch mode will edit a source file and see no rerun until they manually rebuild. From the developer's perspective the runner appears stuck or — worse — the next rerun, triggered by an unrelated test edit, will silently exercise the previous dist build, masking whether the source edit actually fixed the issue. CONTRIBUTING.md advertises this exact script as "watch mode for integration tests," which reinforces the misleading expectation that source edits feed back into the run.\n\nStep-by-step proof.\n1. Run pnpm test:integration:watch. pnpm run build produces packages/*/dist/index.mjs once; vitest starts watching.\n2. Edit packages/client/src/<anything>.ts (e.g., change a public method's behavior).\n3. Vitest does not rerun: the dependency graph for the integration project resolves @langfuse/client to packages/client/dist/index.mjs, which has not been regenerated.\n4. Conversely, edit tests/integration/<some>.test.ts — vitest reruns immediately, since test files aren't aliased through dist.\n5. Manually run pnpm -r build in another terminal: dist files are rewritten, vitest does pick that up and reruns. This proves the watcher is healthy; the missing piece is the source→dist rebuild step.\n\nAddressing the refutation. The refutation argues this is intentional: integration tests are meant to verify built artifacts, and the script's :watch suffix refers to vitest's watch mode rather than a source-watch build. Both points are technically true and explain why the one-shot test:integration script (which uses the same single-build pattern) is harmless. But the watch variant is a different ergonomic contract — :watch scripts in JavaScript tooling almost universally imply "keep my feedback loop closed across the change I'm most likely to make," which for an SDK monorepo is editing package source. Running the watcher against frozen dist outputs gives the same loop only for test-file edits while silently degrading source-file edits, which is the misleading part. The fix doesn't have to be a redesign: documenting that users should run pnpm -r build --watch (or turbo run build --watch) alongside it, or wiring the two together with the existing turbo/concurrently tooling, would resolve it. As-is, the script's behavior diverges from its name in a way that will cost developer time.\n\nSeverity. Nit. This is a developer-convenience script with no production-correctness impact and a trivial workaround once you know about it. Worth a small follow-up either in the script body or in CONTRIBUTING.md's "Run integration tests in watch mode" callout.