Merge pull request #57 from constructive-io/devin/1773716478-env-and-testing-skills

Add constructive-env and constructive-testing skills

Author: pyramation

skills/constructive-env/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: constructive-env
+description: Unified environment configuration for Constructive and PGPM projects — typed defaults, env var parsing, config file discovery, and hierarchical option merging. Use when asked to "configure environment", "set env vars", "manage defaults", "use getEnvOptions", "configure database connection", "set up server config", "configure SMTP", "configure CDN", "manage configuration hierarchy", or when working with @pgpmjs/env or @constructive-io/graphql-env.
+compatibility: Node.js 18+, @pgpmjs/env, @constructive-io/graphql-env
+metadata:
+  author: constructive-io
+  version: "1.0.0"
+---
+
+# Constructive Environment Configuration
+
+Unified, type-safe environment configuration for all Constructive and PGPM projects. Two packages work together to provide a clean, hierarchical configuration system with sensible defaults.
+
+## When to Apply
+
+Use this skill when:
+- Configuring database connections, server settings, CDN, SMTP, or jobs programmatically
+- Understanding how environment variables map to typed configuration objects
+- Writing code that needs to read environment-aware configuration
+- Choosing between `@pgpmjs/env` and `@constructive-io/graphql-env`
+- Understanding the merge hierarchy (defaults → env vars → runtime overrides)
+
+## Architecture Overview
+
+Two packages form a layered configuration system:
+
+```
+@pgpmjs/types          →  PgpmOptions interface + pgpmDefaults
+    ↓
+@pgpmjs/env            →  getEnvVars() + loadConfigSync() + getEnvOptions()
+    ↓  (extends)
+@constructive-io/graphql-types  →  ConstructiveOptions interface + constructiveDefaults
+    ↓
+@constructive-io/graphql-env    →  getGraphQLEnvVars() + getEnvOptions()
+```
+
+### Which Package to Import
+
+| You're working in... | Import from |
+|----------------------|-------------|
+| PGPM packages (`pgpm/*`) | `@pgpmjs/env` |
+| PostgreSQL tools (`postgres/*`) | `@pgpmjs/env` or `pg-env` |
+| GraphQL server, explorer, codegen | `@constructive-io/graphql-env` |
+| Constructive CLI commands | `@constructive-io/graphql-env` |
+| Job functions, SMTP | `@pgpmjs/env` |
+| Tests (pgsql-test based) | `@pgpmjs/env` (via `getConnEnvOptions`) |
+
+**Rule of thumb:** If your code needs GraphQL/Graphile/API options, use `@constructive-io/graphql-env`. Otherwise, use `@pgpmjs/env`.
+
+## Merge Hierarchy
+
+Options are merged in this order (later overrides earlier):
+
+1. **Defaults** — `pgpmDefaults` (+ `constructiveGraphqlDefaults` for GraphQL layer)
+2. **Config file** — `pgpm.json` or `pgpm.config.js` (rarely needed — see [references/config-file.md](references/config-file.md))
+3. **Environment variables** — parsed from `process.env`
+4. **Runtime overrides** — passed programmatically to `getEnvOptions()`
+
+In practice, most projects only use layers 1, 3, and 4. Config files are a last resort for shared workspace settings.
+
+Arrays are **replaced**, not concatenated — the later source wins completely.
+
+## Quick Start
+
+### Core PGPM Options
+
+```typescript
+import { getEnvOptions } from '@pgpmjs/env';
+
+// Get fully merged options (defaults + config + env + overrides)
+const opts = getEnvOptions();
+
+// With runtime overrides
+const opts = getEnvOptions({
+  pg: { database: 'mydb' },
+  deployment: { fast: true }
+});
+
+// With custom working directory and env object
+const opts = getEnvOptions({}, '/path/to/project', process.env);
+```
+
+### Constructive Options (includes GraphQL)
+
+```typescript
+import { getEnvOptions } from '@constructive-io/graphql-env';
+
+// Gets everything: PGPM defaults + GraphQL defaults + config + env + overrides
+const opts = getEnvOptions({
+  pg: { database: 'constructive' },
+  api: { isPublic: true }
+});
+```
+
+### Specialized Accessors
+
+```typescript
+import { getConnEnvOptions, getDeploymentEnvOptions } from '@pgpmjs/env';
+
+// Database connection options with roles resolved
+const connOpts = getConnEnvOptions({ prefix: 'test-' });
+
+// Deployment options only
+const deployOpts = getDeploymentEnvOptions({ fast: true });
+```
+
+## Type System
+
+### PgpmOptions (core)
+
+```typescript
+interface PgpmOptions {
+  db?: Partial<PgTestConnectionOptions>;  // DB config, roles, connections
+  pg?: Partial<PgConfig>;                 // PostgreSQL connection (host, port, user, etc.)
+  server?: ServerOptions;                 // HTTP server (host, port, trustProxy, origin)
+  cdn?: CDNOptions;                       // S3/MinIO file storage
+  deployment?: DeploymentOptions;         // Migration deployment settings
+  migrations?: MigrationOptions;          // Code generation settings
+  jobs?: JobsConfig;                      // Job worker/scheduler config
+  errorOutput?: ErrorOutputOptions;       // Error formatting
+  smtp?: SmtpOptions;                     // Email configuration
+}
+```
+
+### ConstructiveOptions (extends PgpmOptions)
+
+```typescript
+interface ConstructiveOptions extends PgpmOptions {
+  graphile?: GraphileOptions;             // PostGraphile schema config
+  features?: GraphileFeatureOptions;      // Feature flags (inflection, PostGIS)
+  api?: ApiOptions;                       // API routing (public/admin, roles, schemas)
+}
+```
+
+## Utility Functions
+
+### Env Var Parsers
+
+```typescript
+import { parseEnvBoolean, parseEnvNumber } from '@pgpmjs/env';
+
+parseEnvBoolean('true');    // true
+parseEnvBoolean('1');       // true
+parseEnvBoolean('yes');     // true
+parseEnvBoolean('false');   // false
+parseEnvBoolean(undefined); // undefined
+
+parseEnvNumber('5432');     // 5432
+parseEnvNumber('invalid');  // undefined
+```
+
+### Node Environment
+
+```typescript
+import { getNodeEnv } from '@pgpmjs/env';
+
+const env = getNodeEnv(); // 'development' | 'production' | 'test'
+```
+
+## Anti-Patterns
+
+**Never do this:**
+
+```typescript
+// BAD: Manual env var access scattered throughout code
+const host = process.env.PGHOST || 'localhost';
+const port = parseInt(process.env.PGPORT || '5432');
+const usePublic = process.env.API_IS_PUBLIC === 'true';
+```
+
+**Do this instead:**
+
+```typescript
+// GOOD: Use the unified configuration system
+import { getEnvOptions } from '@pgpmjs/env';
+const opts = getEnvOptions();
+const { host, port } = opts.pg;
+```
+
+```typescript
+// GOOD: For Constructive/GraphQL packages
+import { getEnvOptions } from '@constructive-io/graphql-env';
+const opts = getEnvOptions();
+const { isPublic } = opts.api;
+```
+
+## Reference Guide
+
+| Reference | Topic | Consult When |
+|-----------|-------|--------------|
+| [references/env-vars.md](references/env-vars.md) | Source file locations for env vars and types | Finding which source file defines a specific env var or type |
+| [references/defaults.md](references/defaults.md) | Default values for all configuration | Understanding what values are used when nothing is overridden |
+| [references/config-file.md](references/config-file.md) | Config file reference (last resort) | Only when you specifically need a `pgpm.json` — this is rarely needed |
+
+## Cross-References
+
+- `pgpm` skill (`references/env.md`) — The `pgpm env` CLI command for shell-level env var management
+- `constructive-server-config` skill — Server-specific env vars and startup configuration
+- `constructive-deployment` skill — Deployment-specific configuration
+- `constructive-functions` skill — Using `parseEnvBoolean` in Knative functions

skills/constructive-env/references/config-file.md

@@ -0,0 +1,30 @@
+# Config File Reference (Advanced / Last Resort)
+
+Config files (`pgpm.json` / `pgpm.config.js`) are supported but **should rarely be needed**. The preferred approach is to use environment variables and runtime overrides via `getEnvOptions()`.
+
+Config files exist primarily for workspaces that need shared base settings across many packages (e.g., a monorepo where every package shares the same DB extensions list).
+
+## When You Might Need a Config File
+
+- You have a large workspace where many packages share the same non-default settings
+- You need dynamic configuration that depends on runtime logic (`pgpm.config.js` only)
+- You're working with `pgpm init workspace` which generates one automatically
+
+**In most cases, env vars + `getEnvOptions()` overrides are sufficient.**
+
+## How It Works
+
+`loadConfigSync(cwd)` walks up the directory tree from `cwd` looking for `pgpm.config.js` (checked first) or `pgpm.json`. The first found is used. If none is found, an empty object is returned and defaults still apply.
+
+Config file values sit in the merge hierarchy between defaults and env vars:
+
+```
+defaults → config file → env vars → runtime overrides
+```
+
+Env vars always override config file values.
+
+## Source
+
+- **Config loading logic:** `pgpm/env/src/config.ts`
+- **Workspace resolution:** `pgpm/env/src/workspace.ts`

skills/constructive-env/references/defaults.md

@@ -0,0 +1,91 @@
+# Default Configuration Values
+
+These defaults are applied as the base layer before config file, env vars, and runtime overrides.
+
+## PGPM Core Defaults (`pgpmDefaults`)
+
+Source: `@pgpmjs/types`
+
+The core PGPM defaults provide base values for database connection, server, and deployment configuration. These are used by `@pgpmjs/env`'s `getEnvOptions()`.
+
+Key defaults include:
+
+- **`db.rootDb`**: `'postgres'`
+- **`db.prefix`**: `'test-db-'`
+- **`db.extensions`**: `['plpgsql', 'uuid-ossp']`
+- **`db.connections.app`**: Default app-level user/password
+- **`db.connections.admin`**: Default admin user/password
+- **`db.roles`**: Default role definitions
+- **`server.port`**: `3000`
+- **`server.host`**: `'localhost'`
+- **`deployment.useTx`**: `true`
+- **`deployment.fast`**: `false`
+- **`deployment.usePlan`**: `true`
+- **`deployment.cache`**: `false`
+
+## GraphQL Defaults (`constructiveGraphqlDefaults`)
+
+Source: `@constructive-io/graphql-types`
+
+### Graphile Defaults (`graphileDefaults`)
+
+```typescript
+{
+  schema: [],       // No schemas exposed by default
+  extends: [],      // No preset extensions
+  preset: {},       // No preset overrides
+}
+```
+
+### Feature Defaults (`graphileFeatureDefaults`)
+
+```typescript
+{
+  simpleInflection: true,      // Use PgSimplifyInflection
+  oppositeBaseNames: true,     // Use opposite base names for relations
+  postgis: true,               // Enable PostGIS support
+}
+```
+
+### API Defaults (`apiDefaults`)
+
+```typescript
+{
+  enableServicesApi: true,         // Services API routing enabled
+  exposedSchemas: [],              // No schemas exposed by default
+  anonRole: 'administrator',      // Default anonymous role
+  roleName: 'administrator',      // Default authenticated role
+  defaultDatabaseId: 'hard-coded', // Default database ID
+  isPublic: true,                  // Public API mode (domain routing)
+  metaSchemas: [
+    'services_public',
+    'metaschema_public',
+    'metaschema_modules_public',
+  ],
+}
+```
+
+## Combined Defaults (`constructiveDefaults`)
+
+When using `@constructive-io/graphql-env`, the full defaults are a deep merge of:
+
+```typescript
+constructiveDefaults = deepmerge.all([
+  pgpmDefaults,
+  constructiveGraphqlDefaults  // { graphile, features, api }
+]);
+```
+
+This means all PGPM defaults are preserved and the GraphQL-specific defaults are layered on top.
+
+## How Defaults Are Applied
+
+Defaults form the first layer in the merge hierarchy:
+
+```
+defaults → config file → env vars → runtime overrides
+```
+
+If you set a value in a config file, it overrides the default. If you set an env var, it overrides both the default and the config file. Runtime overrides win over everything.
+
+**Array behavior**: Arrays are **replaced**, not concatenated. If the default `db.extensions` is `['plpgsql', 'uuid-ossp']` and you set `DB_EXTENSIONS=postgis`, the result is `['postgis']` — the default array is fully replaced.

skills/constructive-env/references/env-vars.md

@@ -0,0 +1,46 @@
+# Environment Variables Reference
+
+The canonical source of truth for all recognized environment variables lives in the source code. Do not maintain a separate list — always refer to these files directly.
+
+## Source Files
+
+### Core PGPM Env Vars
+
+**File:** `pgpm/env/src/env.ts` in the `constructive` repo
+
+This file defines `getEnvVars()` which maps `process.env` keys to the `PgpmOptions` type. Every env var the system recognizes is defined here via conditional spreads:
+
+```typescript
+// Pattern used throughout env.ts:
+...(process.env.PGHOST && { host: process.env.PGHOST }),
+...(process.env.PGPORT && { port: parseEnvNumber(process.env.PGPORT) }),
+```
+
+Covers: `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`, `DB_*`, `SERVER_*`, `PORT`, `BUCKET_*`, `AWS_*`, `MINIO_*`, `DEPLOYMENT_*`, `JOBS_*`, `SMTP_*`, `PGPM_ERROR_*`
+
+### GraphQL-Specific Env Vars
+
+**File:** `graphql/env/src/env.ts` in the `constructive` repo
+
+This file defines `getGraphQLEnvVars()` which adds GraphQL/Constructive-specific env vars on top of the core PGPM set.
+
+Covers: `GRAPHILE_SCHEMA`, `FEATURES_*`, `API_*`
+
+## Type Definitions
+
+The TypeScript interfaces that define the shape of these options:
+
+- **`PgpmOptions`** — `pgpm/types/src/options.ts`
+- **`ConstructiveOptions`** — `graphql/types/src/constructive.ts`
+- **`GraphileOptions`** — `graphql/types/src/graphile.ts`
+- **`PgConfig`** — `pgpm/types/src/pg.ts`
+
+## Type Parsing
+
+The env parsing uses three type-safe parsers (defined in `pgpm/env/src/env.ts`):
+
+- **`parseEnvBoolean(val)`** — Accepts `'true'`, `'1'`, `'yes'` (case-insensitive) as `true`
+- **`parseEnvNumber(val)`** — Uses `Number()`, returns `undefined` if `NaN`
+- **`parseEnvStringArray(val)`** — Splits on comma, trims whitespace, filters empty strings
+
+If an env var is not set, that key is omitted entirely from the options object — it does not get set to `undefined`. This allows the merge hierarchy to fall through to defaults or config file values.