env: enforce OS_ prefix for all ObjectStack-owned environment variables

[xuyushun441-sys]

Background

All ObjectStack-owned environment variables should be prefixed OS_* for namespace hygiene. Audit (see chat) surfaced inconsistencies in three buckets:

1. Internal vars without OS_ prefix — should be renamed (no upstream convention to honour).
2. Existing OS_ canonical with legacy alias — alias should be deprecated.
3. Third-party / SDK conventions — keep as-is (e.g. OPENAI_API_KEY, TURSO_DATABASE_URL, BETTER_AUTH_URL, OAuth *_CLIENT_ID/SECRET, RESEND_API_KEY). Out of scope for this issue.

PORT and DATABASE_URL are Heroku/12-factor industry conventions; they keep working as silent fallbacks for OS_RUNTIME_PORT / OS_DATABASE_URL without deprecation noise.

Scope (Categories ① + ②)

① Rename (internal, no upstream)

Current	New
AUTH_BASE_URL	OS_AUTH_BASE_URL
CORS_ENABLED	OS_CORS_ENABLED
CORS_ORIGIN	OS_CORS_ORIGIN
CORS_CREDENTIALS	OS_CORS_CREDENTIALS
CORS_MAX_AGE	OS_CORS_MAX_AGE
AI_MODEL	OS_AI_MODEL
MCP_SERVER_ENABLED	OS_MCP_SERVER_ENABLED
MCP_SERVER_NAME	OS_MCP_SERVER_NAME
MCP_SERVER_TRANSPORT	OS_MCP_SERVER_TRANSPORT
OBJECTSTACK_DEV_CRYPTO_KEY	OS_DEV_CRYPTO_KEY
OBJECTSTACK_METADATA_WRITABLE	OS_METADATA_WRITABLE
OBJECTSTACK_NODE_ID	OS_NODE_ID

Affected files: packages/cli/src/commands/serve.ts, packages/plugins/plugin-hono-server/src/hono-plugin.ts, packages/adapters/hono/src/index.ts, packages/plugins/plugin-auth/src/auth-manager.ts, packages/services/service-ai/src/plugin.ts, packages/plugins/plugin-mcp-server/src/plugin.ts, examples/app-crm/test-backend.mjs, packages/objectql/src/protocol-meta-types-rich.test.ts, packages/plugins/plugin-webhooks/src/webhook-outbox-plugin.ts.

② Deprecate legacy alias (canonical OS_ already exists)

Legacy	Canonical	Action
AUTH_SECRET	OS_AUTH_SECRET	Keep fallback, log deprecation warning once
ROOT_DOMAIN	OS_ROOT_DOMAIN	Keep fallback, log deprecation warning once
OS_MULTI_TENANT	OS_MULTI_ORG_ENABLED	Keep fallback, log deprecation warning once

Behaviour

• For ①: keep reading legacy name as silent fallback for at least one minor release so user .env files don't break, but emit a one-shot console.warn('[OS] Env var X is deprecated; use OS_X') on first read.
• For ②: same — fallback + one-shot deprecation warning.
• No legacy reads for brand-new vars (would never have been published).

Out of scope

• Category ③ third-party conventions.
• PORT / DATABASE_URL industry fallbacks remain silent.

Acceptance

• All call sites read OS_-prefixed name first, fall back to legacy.
• Deprecation warning helper is centralised (not duplicated).
• Docs / .env.example / changesets updated.
• AGENTS.md guard: "All new env vars MUST start with OS_".
• pnpm test green.

[xuyushun441-sys]

Implementation complete

All Category ① (rename) and Category ② (deprecate alias) work has landed.

Helper: readEnvWithDeprecation(preferred, legacy) in @objectstack/types — one-shot deprecation warning per (preferred, legacy) pair.

Renamed (with legacy fallback):

• OS_AUTH_SECRET ← AUTH_SECRET
• OS_AUTH_BASE_URL ← AUTH_BASE_URL
• OS_ROOT_DOMAIN ← ROOT_DOMAIN
• OS_MULTI_ORG_ENABLED ← OS_MULTI_TENANT
• OS_CORS_{ENABLED,ORIGIN,CREDENTIALS,MAX_AGE} ← CORS_*
• OS_AI_MODEL ← AI_MODEL
• OS_MCP_SERVER_{ENABLED,NAME,TRANSPORT} ← MCP_SERVER_*
• OS_NODE_ID ← OBJECTSTACK_NODE_ID
• OS_METADATA_WRITABLE ← OBJECTSTACK_METADATA_WRITABLE
• OS_DEV_CRYPTO_KEY ← OBJECTSTACK_DEV_CRYPTO_KEY
• OS_HOME ← OBJECTSTACK_HOME

Touched packages: types, runtime, cli, objectql, plugin-auth, plugin-hono-server, plugin-dev, plugin-mcp-server, plugin-webhooks, service-ai, service-settings, hono adapter.

Guard: added rule #9 to AGENTS.md mandating OS_ prefix and listing third-party exceptions.

Tests: all green

• @objectstack/types: 4/4 (env helper)
• @objectstack/objectql: 412/412
• @objectstack/runtime: 303/303
• @objectstack/plugin-auth: 85/85
• @objectstack/plugin-hono-server: 38/38
• @objectstack/plugin-mcp-server: 25/25
• @objectstack/plugin-webhooks: 45/45
• @objectstack/plugin-dev: 7/7
• @objectstack/service-ai: 405/405
• @objectstack/service-settings: 78/78
• @objectstack/hono: 67/67

Category ③ (third-party SDK conventions: OPENAI_API_KEY, TURSO_*, BETTER_AUTH_URL, OAuth *_CLIENT_ID/SECRET, RESEND_API_KEY, POSTMARK_TOKEN, AI_GATEWAY_*, PORT, DATABASE_URL, NODE_ENV) — not handled, per user instruction.

Changeset: .changeset/env-os-prefix-migration.md

[xuyushun441-sys]

Round 2: absorb more legacy names

Per follow-up direction, the following previously-excluded vars are now canonicalised under OS_ with their original names kept as legacy fallbacks:

Canonical	Legacy fallback(s)
OS_PORT	PORT
OS_DATABASE_URL	DATABASE_URL
OS_AUTH_URL	AUTH_BASE_URL, BETTER_AUTH_URL, OS_AUTH_BASE_URL (round-1 alias retired)
OS_AUTH_SECRET	AUTH_SECRET, BETTER_AUTH_SECRET

Helper extended: readEnvWithDeprecation(preferred, legacy: string | string[]) now accepts an array of legacy names (first match wins, warns for the matched name).

Still NOT renamed (third-party SDK or OS-level convention only): NODE_ENV, HOME, OPENAI_API_KEY, TURSO_*, OAuth *_CLIENT_ID/SECRET, RESEND_API_KEY, POSTMARK_TOKEN, AI_GATEWAY_*, SMTP_* (framework code does not currently read SMTP env vars directly — it uses MAIL_SMTP_HOST-style settings keys).

Tests: types 6/6, runtime 303/303, plugin-auth 85/85.