feat: Convex integration — sync env vars to Convex deployments

[sergical]

Summary

Adds @varlock/convex-integration, a new integration package that syncs varlock-resolved environment variables to Convex deployments.

What this enables

Users can tag specific env vars in their .env.schema with @syncTarget(convex) to selectively push them to a Convex backend — keeping auth-only secrets (like 1Password tokens) out of the sync.

User experience

1. Install and configure — add the plugin to your .env.schema:

# @plugin(@varlock/convex-integration)
# ---

# These get synced to Convex
# @syncTarget(convex)
DATABASE_URL=postgres://localhost:5432/mydb

# @sensitive
# @syncTarget(convex)
API_KEY=op("op://vault/item/key")

# This stays local (no @syncTarget)
OP_TOKEN=ops_my_1password_token

2. Preview what will be synced:

varlock-convex-sync --dry-run
# Dry run - would sync the following variables to Convex:
#   DATABASE_URL
#   API_KEY [sensitive]
#   __VARLOCK_ENV (blob, 299 bytes)

3. Push to Convex:

CONVEX_DEPLOY_KEY=prod:my-project|token varlock-convex-sync
# ✔ Successfully set 2 environment variables (on deployment my-project)
# ✔ Successfully set __VARLOCK_ENV blob
# Synced 2 variables to Convex (+ __VARLOCK_ENV blob)

4. In CI/deploy pipelines:

npx convex deploy --cmd "varlock-convex-sync"

What gets pushed

• Individual env vars via npx convex env set --from-file (for process.env.KEY access)
• __VARLOCK_ENV blob containing a minimal graph (for import { ENV } from 'varlock/env' support in Convex functions)
• Items without @syncTarget(convex) are excluded from both

CLI options

Flag	Description
--deploy-key <key>	Convex deploy key (or use CONVEX_DEPLOY_KEY env var)
--env <name>	Environment name (e.g., production)
--path <path>	Path to .env.schema or project directory
--prod	Pass --prod flag to Convex CLI
--no-blob	Skip pushing the __VARLOCK_ENV blob
--no-individual	Skip pushing individual env vars
--dry-run	Preview changes without pushing

Changes

New package: @varlock/convex-integration

• Plugin (src/plugin.ts) — registers @syncTarget item decorator and convexDeployKey data type
• Sync logic (src/index.ts) — resolves env graph, filters by @syncTarget(convex), builds minimal blob, pushes via Convex CLI
• CLI (src/cli.ts) — varlock-convex-sync binary with dry-run, --prod, --no-blob support
• Unit tests (10 tests) — blob building, filtering, edge cases
• Smoke tests (7 tests) — end-to-end serialization, syncTargets population, sensitivity flags

Core changes (varlock)

• env-graph.ts — add syncTargets?: Array<string> to SerializedEnvGraph config items, populated from @syncTarget() function-call decorators during serialization
• runtime/env.ts — guard Buffer access with typeof Buffer !== 'undefined' for serverless runtimes (Convex) that lack a global Buffer

Test results

• 10/10 unit tests passing (packages/integrations/convex/test/sync.test.ts)
• 7/7 smoke tests passing (smoke-tests/tests/convex.test.ts)
• Tested live sync against a real Convex dev deployment

[changeset-bot]

🦋 Changeset detected

Latest commit: 16bdcc9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
@varlock/convex-integration	Minor
varlock	Patch
@varlock/astro-integration	Patch
@varlock/nextjs-integration	Patch
@varlock/vite-integration	Patch
@varlock/1password-plugin	Patch
@varlock/aws-secrets-plugin	Patch
@varlock/azure-key-vault-plugin	Patch
@varlock/bitwarden-plugin	Patch
@varlock/google-secret-manager-plugin	Patch
@varlock/infisical-plugin	Patch
@varlock/pass-plugin	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[philmillman]

Thanks for this @sergical ! We probably want to think through sync as a first class concept since people are already doing this via varlock load --format env with other platforms. We also tend to use 'integration' for frameworks and 'plugin' for platforms so this might be more of a plugin in that sense but it can get a bit muddy. I'll let @theoephraim get into any specifics he may have thought through already.

[sergical]

@philmillman yeah we chatted through it a bit last night.

the reason i didn't go with a plugin here is because it is setup as a pull, where this with the push and sync felt a bit more integration-y

but definitely hear you on the fact that "push" needs to be thought of a bit more before making a decision on the right approach, this was mostly a POC

also the idea of tags was brought up as opposed to explicit syncTarget

will sync up again and proceed as best fitted here