composable.env 0.1.0 → 0.1.1

package/examples/fullstack/env/.env.local

@@ -0,0 +1,18 @@
+# Personal overrides — DO NOT commit this file (gitignored)
+# Applied last, overrides everything else
+# Each developer can customize their local environment
+
+# Use a custom local database port (e.g., if 5432 is taken)
+DATABASE_PORT=5433
+
+# Verbose logging during development
+LOG_LEVEL=debug
+
+# Point the web app at your local API
+API_URL=http://localhost:4000
+
+# Staging secrets (for testing against staging — get from team vault)
+# DATABASE_STAGING_PASSWORD=ask-your-team-lead
+# AUTH_STAGING_JWT_SECRET=ask-your-team-lead
+# STORAGE_STAGING_ACCESS_KEY=ask-your-team-lead
+# STORAGE_STAGING_SECRET_KEY=ask-your-team-lead

package/examples/fullstack/env/.env.shared

@@ -0,0 +1,19 @@
+# Shared team values — commit this file to version control
+# These are applied AFTER components, BEFORE .env.local
+# No secrets here — use .env.local or a secrets manager for those
+
+# Staging hosts
+DATABASE_STAGING_HOST=db-staging.example.com
+DATABASE_STAGING_USER=app_staging
+REDIS_STAGING_HOST=redis-staging.example.com
+STORAGE_STAGING_BUCKET=myapp-uploads-staging
+
+# Production hosts
+DATABASE_PROD_HOST=db.example.com
+DATABASE_PROD_USER=app_prod
+REDIS_PROD_HOST=redis.example.com
+STORAGE_PROD_BUCKET=myapp-uploads-prod
+
+# Shared across all environments
+API_URL=http://localhost:4000
+APP_NAME=MyApp

package/examples/fullstack/env/components/auth.env

@@ -0,0 +1,19 @@
+NAMESPACE=AUTH
+
+[default]
+JWT_SECRET=dev-secret-change-me
+JWT_EXPIRES_IN=7d
+BCRYPT_ROUNDS=10
+SESSION_TTL=86400
+
+[staging]
+JWT_SECRET=${AUTH_STAGING_JWT_SECRET}
+JWT_EXPIRES_IN=1d
+BCRYPT_ROUNDS=12
+SESSION_TTL=3600
+
+[production]
+JWT_SECRET=${AUTH_PROD_JWT_SECRET}
+JWT_EXPIRES_IN=1d
+BCRYPT_ROUNDS=14
+SESSION_TTL=3600

package/examples/fullstack/env/components/database.env

@@ -0,0 +1,21 @@
+NAMESPACE=DATABASE
+
+[default]
+HOST=localhost
+PORT=5432
+NAME=myapp_dev
+USER=postgres
+PASSWORD=postgres
+
+[staging]
+HOST=${DATABASE_STAGING_HOST}
+NAME=myapp_staging
+USER=${DATABASE_STAGING_USER}
+PASSWORD=${DATABASE_STAGING_PASSWORD}
+
+[production]
+HOST=${DATABASE_PROD_HOST}
+PORT=5432
+NAME=myapp
+USER=${DATABASE_PROD_USER}
+PASSWORD=${DATABASE_PROD_PASSWORD}

package/examples/fullstack/env/components/redis.env

@@ -0,0 +1,22 @@
+NAMESPACE=REDIS
+
+[default]
+HOST=localhost
+PORT=6379
+URL=redis://localhost:6379
+DB=0
+
+[staging]
+HOST=${REDIS_STAGING_HOST}
+PORT=6379
+URL=redis://${REDIS_STAGING_HOST}:6379
+DB=0
+
+[development]
+DB=1
+
+[production]
+HOST=${REDIS_PROD_HOST}
+PORT=6379
+URL=redis://${REDIS_PROD_HOST}:6379
+DB=0

package/examples/fullstack/env/components/storage.env

@@ -0,0 +1,22 @@
+NAMESPACE=STORAGE
+
+[default]
+PROVIDER=local
+LOCAL_PATH=./uploads
+MAX_FILE_SIZE=10485760
+
+[staging]
+PROVIDER=s3
+S3_BUCKET=${STORAGE_STAGING_BUCKET}
+S3_REGION=us-east-1
+S3_ACCESS_KEY=${STORAGE_STAGING_ACCESS_KEY}
+S3_SECRET_KEY=${STORAGE_STAGING_SECRET_KEY}
+MAX_FILE_SIZE=52428800
+
+[production]
+PROVIDER=s3
+S3_BUCKET=${STORAGE_PROD_BUCKET}
+S3_REGION=us-east-1
+S3_ACCESS_KEY=${STORAGE_PROD_ACCESS_KEY}
+S3_SECRET_KEY=${STORAGE_PROD_SECRET_KEY}
+MAX_FILE_SIZE=104857600

package/examples/fullstack/env/contracts/api.contract.ts

@@ -0,0 +1,24 @@
+import type { ServiceContract } from 'composable.env';
+
+export const ApiContract: ServiceContract = {
+  name: 'api',
+  location: 'apps/api',
+
+  // Template mappings — compose variables into connection strings
+  required: {
+    DATABASE_URL: 'postgresql://${DATABASE_USER}:${DATABASE_PASSWORD}@${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_NAME}',
+    REDIS_URL: 'REDIS_URL',
+    JWT_SECRET: 'AUTH_JWT_SECRET',
+  },
+
+  // Optional vars with fallback defaults
+  optional: {
+    LOG_LEVEL: 'LOG_LEVEL',
+    CORS_ORIGIN: 'CORS_ORIGIN',
+  },
+
+  defaults: {
+    LOG_LEVEL: 'info',
+    CORS_ORIGIN: 'http://localhost:3000',
+  },
+};

package/examples/fullstack/env/contracts/web.contract.ts

@@ -0,0 +1,20 @@
+import type { ServiceContract } from 'composable.env';
+
+export const WebContract: ServiceContract = {
+  name: 'web',
+  location: 'apps/web',
+
+  required: {
+    NEXT_PUBLIC_API_URL: 'API_URL',
+  },
+
+  optional: {
+    NEXT_PUBLIC_APP_NAME: 'APP_NAME',
+    NEXT_PUBLIC_SESSION_TTL: 'AUTH_SESSION_TTL',
+  },
+
+  defaults: {
+    NEXT_PUBLIC_API_URL: 'http://localhost:4000',
+    NEXT_PUBLIC_APP_NAME: 'MyApp',
+  },
+};

package/examples/fullstack/env/contracts/worker.contract.ts

@@ -0,0 +1,28 @@
+import type { ServiceContract } from 'composable.env';
+
+export const WorkerContract: ServiceContract = {
+  name: 'worker',
+  location: 'apps/worker',
+
+  required: {
+    DATABASE_URL: 'postgresql://${DATABASE_USER}:${DATABASE_PASSWORD}@${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_NAME}',
+    REDIS_URL: 'REDIS_URL',
+  },
+
+  // Secret vars — validated the same as required, but semantically separated
+  secret: {
+    STORAGE_ACCESS_KEY: 'STORAGE_S3_ACCESS_KEY',
+    STORAGE_SECRET_KEY: 'STORAGE_S3_SECRET_KEY',
+  },
+
+  optional: {
+    STORAGE_BUCKET: 'STORAGE_S3_BUCKET',
+    STORAGE_REGION: 'STORAGE_S3_REGION',
+    MAX_FILE_SIZE: 'STORAGE_MAX_FILE_SIZE',
+  },
+
+  defaults: {
+    STORAGE_REGION: 'us-east-1',
+    MAX_FILE_SIZE: '10485760',
+  },
+};

package/examples/fullstack/env/profiles/default.json

@@ -0,0 +1,5 @@
+{
+  "name": "Default",
+  "description": "All available components — uses [default] sections for local development",
+  "components": ["database", "redis", "auth", "storage"]
+}

package/examples/fullstack/env/profiles/development.json

@@ -0,0 +1,7 @@
+{
+  "name": "Development",
+  "description": "Local development — overrides redis DB for isolation",
+  "components": {
+    "redis": ["default", "development"]
+  }
+}

package/examples/fullstack/env/profiles/production.json

@@ -0,0 +1,4 @@
+{
+  "name": "Production",
+  "description": "Production environment with remote services"
+}

package/examples/fullstack/env/profiles/staging.json

@@ -0,0 +1,5 @@
+{
+  "name": "Staging",
+  "description": "Staging environment — extends production with staging-specific overrides",
+  "extends": "production"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "composable.env",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Composable environment management: build .env files for every service from reusable components, profiles, and contracts.",
   "type": "module",
   "main": "dist/src/index.js",
@@ -9,7 +9,8 @@
     "cenv": "dist/cli/index.js"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "examples/"
   ],
   "scripts": {
     "build": "tsc",