feat: add observability-and-env skill with pino logger, Zod env schemas, and centralized Sentry bootstrap

[carlosvin]

What has been changed

This PR ports the observability and environment patterns proven in production to the template as a reusable skill + working code.

New files

File	Purpose
src/env/runtimeEnvSchema.ts	Shared DeploymentEnv, LogLevel Zod enums and optional preprocessors
src/env/webEnv.ts	WebServerEnvSchema (full) + WebPublicEnvSchema (browser-safe slice); singletons parsed once
src/utils/logger.ts	createModuleLogger(name, options) pino factory — no process.env inside
src/utils/serverLogger.ts	createServerLogger(name) — binds webServerEnv.ENV and LOG_LEVEL
src/middleware/webEnv.ts	webEnvMiddleware — injects ctx.context.publicEnv for server functions
instrument.env.mjs	Plain JS resolveSentryBootstrapEnv() — reads process.env once before TS loads
instrument.shared.mjs	initSentry({ serverName, dsn, environment, release }) — all values pre-resolved by caller
skills/src/observability-and-env.skill.yaml	New skill encoding all the patterns
.agents/skills/observability-and-env/SKILL.md	Generated skill artifact

Modified files

File	Change
instrument.server.mjs	Simplified to 9 lines using resolveSentryBootstrapEnv() + initSentry()
src/services/observability/index.ts	Uses webPublicEnv.SENTRY_DSN instead of process.env.VITE_SENTRY_DSN
src/middleware/auth.ts	Uses webServerEnv.AUTH_HEADER_NAME instead of process.env.AUTH_HEADER_NAME
package.json	Add pino, pino-pretty; copy all instrument.*.mjs in build script
.env.example	Document ENV, LOG_LEVEL, and canonical SENTRY_DSN
AGENTS.md	§9: document pino + Sentry bootstrap patterns; §13: replace window.__ENV__ with loader/middleware pattern
skills/registry.json	Register new skill

Key invariants enforced

• process.env is read only in src/env/*.ts (schema parse) and instrument.env.mjs (bootstrap)
• Logger options (logLevel, environment) are passed as arguments — never resolved inside the factory
• Public env (ENV, LOG_LEVEL, SENTRY_DSN) reaches the browser via the root loader — no window.__ENV__ global
• Root pino logger created once per process; all module loggers are child() instances

Testing

• npx tsc --noEmit — passes with no errors
• node ./scripts/skills/buildSkills.mjs --check — both skills validate cleanly
• npx @biomejs/biome check src/env/ src/utils/ src/middleware/ src/services/observability/index.ts — no issues

Made with Cursor

[Copilot]

Pull request overview

Introduces a centralized observability + environment-validation foundation for the TanStack Start template: Zod-validated env schemas split into server/public slices, a pino-based module logger factory with a server-bound convenience wrapper, and a three-file Sentry bootstrap pattern (instrument.env.mjs → instrument.shared.mjs → instrument.server.mjs). Existing process.env reads in auth.ts and observability/index.ts are replaced by reads from the validated singletons, and a new webEnvMiddleware plus a new observability-and-env skill are added to document the pattern.

Changes:

• New env schemas (src/env/runtimeEnvSchema.ts, src/env/webEnv.ts) and pino logger factories (src/utils/logger.ts, src/utils/serverLogger.ts).
• Refactored Sentry bootstrap into instrument.env.mjs + instrument.shared.mjs, with instrument.server.mjs reduced to a thin entry point; build script copies all instrument.*.mjs.
• New observability-and-env skill (yaml + dist + generated SKILL.md) plus AGENTS.md/§9/§13 rewrite, README, registry, and pnpm-workspace allowBuilds additions; pino/pino-pretty added as runtime deps.

Reviewed changes

Copilot reviewed 21 out of 24 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/env/runtimeEnvSchema.ts	Shared DeploymentEnv/LogLevel enums and trim-to-undefined preprocessor.
src/env/webEnv.ts	WebServerEnvSchema + WebPublicEnvSchema singletons parsed from process.env.
src/utils/logger.ts	Lazy-singleton root pino logger + createModuleLogger factory.
src/utils/serverLogger.ts	createServerLogger bound to webServerEnv env values.
src/middleware/webEnv.ts	New middleware injecting publicEnv into server-fn context (not yet registered).
src/middleware/auth.ts	Reads AUTH_HEADER_NAME from webServerEnv instead of process.env.
src/services/observability/index.ts	DSN check now uses webPublicEnv.SENTRY_DSN.
instrument.env.mjs	New plain-JS env resolver for Sentry bootstrap.
instrument.shared.mjs	New initSentry helper; pre-resolved values; no env reads.
instrument.server.mjs	Reduced to resolve+init using the new helpers.
package.json	Adds pino, pino-pretty; build script copies instrument.*.mjs.
pnpm-workspace.yaml	New allowBuilds allow-list for native build scripts.
pnpm-lock.yaml	Lockfile churn for pino chain and removed transitive rollup peer pinning.
.env.example	Documents ENV, LOG_LEVEL, SENTRY_DSN (and legacy VITE_SENTRY_DSN).
AGENTS.md	§9 documents pino + Sentry bootstrap; §13 replaces window.__ENV__ with loader/middleware pattern.
skills/src/observability-and-env.skill.yaml	New skill source.
skills/src/tanstack-promptable-fullstack-app-template.skill.yaml	Cross-link to companion skill.
skills/registry.json	Registers the new skill.
skills/README.md	Documents both skills + install command.
skills/dist/observability-and-env.md	Generated portable copy.
skills/dist/tanstack-promptable-fullstack-app-template.md	Cross-link diff.
.agents/skills/observability-and-env/SKILL.md	Generated agent-facing skill artifact.
.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md	Cross-link diff.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (2)

src/env/webEnv.ts:49

• The precedence here resolves VITE_SENTRY_DSN || SENTRY_DSN, meaning the legacy alias wins over the canonical variable. The comment on line 25 calls SENTRY_DSN the canonical name and VITE_SENTRY_DSN the backwards-compatible alias, so during a migration where both are set the documented "use SENTRY_DSN in new config" guidance is contradicted at runtime. Consider webServerEnv.SENTRY_DSN || webServerEnv.VITE_SENTRY_DSN so the canonical value takes priority.

export const webPublicEnv: WebPublicEnv = WebPublicEnvSchema.parse({
	...webServerEnv,
	SENTRY_DSN: webServerEnv.VITE_SENTRY_DSN || webServerEnv.SENTRY_DSN,
})

src/utils/logger.ts:52

• src/utils/logger.ts is described as safe to import from client React components, and pino + pino-pretty are listed as runtime dependencies in package.json. Bundling pino into the browser bundle is heavy (pretty transport spawns a worker thread, etc.) and largely useless on the client. Even with the process.stdout guard, all the pino code (and pino-pretty's worker target string) ends up in the client bundle. Consider either keeping the logger server-only (and providing a thin browser shim) or moving these to devDependencies/optionalDependencies with a dynamic import on the server path.

	// `createModuleLogger` is also imported by client React components, so this
	// must stay safe in a browser bundle where `process.stdout` is undefined.
	// Pretty transport is only enabled in an interactive Node TTY outside of
	// production.
	const isNodeTty = typeof process !== 'undefined' && process.stdout != null && Boolean(process.stdout.isTTY)
	const useTtyPretty = isNodeTty && environment !== 'production'

	// Root is created at the most permissive level ('trace') so per-child level
	// overrides are never filtered out at the root.
	rootLogger = useTtyPretty
		? pino(
				{ level: 'trace' },
				pino.transport({
					target: 'pino-pretty',
					options: { colorize: true, singleLine: true, translateTime: 'HH:MM:ss.l' },
				}),
			)
		: pino({ level: 'trace' })

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.