feat(config): JSON/JSONC-first Config v2

Author: andrewmelchor

.changeset/short-hoops-peel.md

@@ -0,0 +1,6 @@
+---
+"@t-req/core": minor
+"@t-req/app": minor
+---
+
+Add JSON/JSONC-first Config v2 with deterministic layering (profiles + overrides), safe {env:}/{file:} substitutions, and command-resolver support. Improve cookie persistence safety with serialized writes and add coverage for critical config paths.

apps/webdocs/src/content/docs/concepts/variables.md

@@ -89,7 +89,7 @@ X-Request-ID: {{$uuid()}}
 X-Timestamp: {{$timestamp()}}
 
 {
-  "random_value": {{$random(1, 100)}}
+  "random_value": {{$random([1, 100])}}
 }
 ```
 

apps/webdocs/src/content/docs/guides/authentication.md

@@ -68,11 +68,11 @@ const client = createClient({
 
 ```http
 GET https://api.example.com/admin
-Authorization: Basic {{$basicAuth({{username}}, {{password}})}}
+Authorization: Basic {{$basicAuth(["{{username}}", "{{password}}"])}}
 ```
 
-> **Note:** Variables inside resolver calls are interpolated first. The expression
-> `{{$basicAuth({{username}}, {{password}})}}` first becomes `{{$basicAuth(admin, secret)}}`,
+> **Note:** Variables inside resolver calls are interpolated first. With JSON-args, the expression
+> `{{$basicAuth(["{{username}}", "{{password}}"])}}` becomes `{{$basicAuth(["admin", "secret"])}}`,
 > then the resolver is called with literal strings `"admin"` and `"secret"`.
 
 Or pre-encode in the variable:

apps/webdocs/src/content/docs/reference/interpolation.md

@@ -115,7 +115,7 @@ interpolate('User: {{user.name}}', {
 ```
 {{$resolverName()}}
 {{$resolverName(arg1)}}
-{{$resolverName(arg1, arg2)}}
+{{$resolverName(["arg1","arg2"])}}
 ```
 
 ```typescript
@@ -129,7 +129,8 @@ const interp = createInterpolator({
   },
 });
 
-await interp.interpolate('Value: {{$random(1, 10)}}', {});
+// Prefer JSON-array args for unambiguous parsing:
+await interp.interpolate('Value: {{$random([1, 10])}}', {});
 // "Value: 7" (random between 1-10)
 ```
 

examples/core/variables.http

@@ -66,13 +66,14 @@ X-Request-ID: {{$uuid()}}
 ###
 
 ### Using random resolver
-# Resolvers: $random(min,max)
+# Resolvers: prefer JSON-args for unambiguous parsing
+# - $random([min,max])
 POST {{baseUrl}}/test
 Content-Type: application/json
 
 {
-  "testId": "test-{{$random(1000,9999)}}",
-  "value": {{$random(1,100)}}
+  "testId": "test-{{$random([1000,9999])}}",
+  "value": {{$random([1,100])}}
 }
 
 ###

packages/app/README.md

@@ -34,7 +34,8 @@ Uses defaults: bun runtime, bun package manager.
 
 ```
 my-project/
-├── treq.config.ts        # Configuration with baseUrl variable
+├── treq.jsonc            # Project configuration (JSONC-first)
+├── .treq/                # Local state (optional, e.g. cookie jar)
 ├── collection/
 │   ├── auth/
 │   │   └── login.http    # Example POST request
@@ -53,6 +54,9 @@ Execute `.http` files directly from the command line:
 # Execute the first request in a file
 treq run collection/auth/login.http
 
+# Use a config profile
+treq run collection/auth/login.http --profile dev
+
 # Execute a specific request by name
 treq run collection/users.http --name "Get User"
 
@@ -62,7 +66,8 @@ treq run collection/users.http --index 2
 # Pass variables
 treq run collection/auth/login.http --var email=test@example.com --var password=secret
 
-# Use environment file
+# Legacy environment module (kept for compatibility)
+# Loads environments/<env>.ts or environments/<env>.js from the workspace
 treq run collection/auth/login.http --env dev
 
 # Set timeout (in milliseconds)
@@ -78,7 +83,8 @@ treq run collection/auth/login.http --verbose
 |--------|-------------|
 | `--name, -n` | Select request by @name directive |
 | `--index, -i` | Select request by index (0-based) |
-| `--env, -e` | Environment file to load (looks for `.env.<name>`) |
+| `--profile, -p` | Config profile to use |
+| `--env, -e` | Legacy environment module to load (`environments/<env>.ts` or `environments/<env>.js`) |
 | `--var` | Set variable (can be used multiple times) |
 | `--timeout, -t` | Request timeout in milliseconds |
 | `--workspace, -w` | Workspace root directory |
@@ -123,6 +129,7 @@ treq serve --stdio
 | Method | Path | Description |
 |--------|------|-------------|
 | `GET` | `/health` | Server health and version info |
+| `GET` | `/config` | Resolved config summary (supports `?profile=` and `?path=`) |
 | `POST` | `/parse` | Parse `.http` file content |
 | `POST` | `/execute` | Execute HTTP request |
 | `POST` | `/session` | Create new session |
@@ -167,7 +174,7 @@ treq serve --help
 
 The server uses protocol version `1.0`.
 
-`/health` is intentionally lean (OpenCode pattern) and only returns a basic status and server version:
+`/health` is intentionally lean  and only returns a basic status and server version:
 
 ```json
 {

packages/app/src/cmd/init.ts

@@ -36,10 +36,6 @@ export const initCommand: CommandModule<object, InitOptions> = {
   }
 };
 
-// ============================================================================
-// Path Utilities (Bun-native)
-// ============================================================================
-
 const SEP = '/';
 
 function basename(p: string): string {
@@ -202,26 +198,18 @@ async function createProjectStructure(projectPath: string, config: ProjectConfig
 
   // Create directories using Bun shell
   await $`mkdir -p ${projectPath}`.quiet();
-  await $`mkdir -p ${join(projectPath, 'environments')}`.quiet();
+  await $`mkdir -p ${join(projectPath, '.treq')}`.quiet();
   await $`mkdir -p ${join(projectPath, 'collection', 'auth')}`.quiet();
   await $`mkdir -p ${join(projectPath, 'collection', 'users')}`.quiet();
 
   // Write root files
-  await Bun.write(join(projectPath, 'treq.config.ts'), generateConfig());
+  await Bun.write(join(projectPath, 'treq.jsonc'), generateConfig());
   await Bun.write(join(projectPath, 'run.ts'), generateRunScript(config.runtime));
   await Bun.write(join(projectPath, 'package.json'), generatePackageJson(projectName, config));
   await Bun.write(join(projectPath, '.gitignore'), generateGitignore());
 
-  // Write environments
-  await Bun.write(join(projectPath, 'environments', 'dev.ts'), generateDevEnvironment());
-  await Bun.write(join(projectPath, 'environments', 'prod.ts'), generateProdEnvironment());
-
   // Write collection
   await Bun.write(join(projectPath, 'collection', 'auth', 'login.http'), generateLoginRequest());
-  await Bun.write(
-    join(projectPath, 'collection', 'users', '_defaults.ts'),
-    generateFolderDefaults()
-  );
   await Bun.write(
     join(projectPath, 'collection', 'users', 'list.http'),
     generateListUsersRequest()
@@ -230,13 +218,33 @@ async function createProjectStructure(projectPath: string, config: ProjectConfig
 }
 
 export function generateConfig(): string {
-  return `import { defineConfig } from '@t-req/core/config';
-
-export default defineConfig({
-  variables: {
-    baseUrl: '{{baseUrl}}',
+  return `{
+  "variables": {
+    // Default base URL for the included sample requests.
+    // Switch profiles with: treq run ... --profile dev
+    "baseUrl": "https://jsonplaceholder.typicode.com"
+    // Example substitutions:
+    // "apiKey": "{env:API_KEY}",
+    // "authToken": "{file:./secrets/token.txt}"
   },
-});
+  "defaults": {
+    "timeoutMs": 30000
+  },
+  // Uncomment to persist cookies between runs:
+  // "cookies": {
+  //   "enabled": true,
+  //   "jarPath": ".treq/cookies.json"
+  // },
+  "profiles": {
+    "dev": {
+      "variables": { "baseUrl": "http://localhost:3000" },
+      "defaults": { "validateSSL": false }
+    },
+    "prod": {
+      "variables": { "baseUrl": "https://api.example.com" }
+    }
+  }
+}
 `;
 }
 
@@ -245,11 +253,32 @@ export function generateRunScript(runtime: Runtime): string {
 
   return `${shebang}
 import { createClient } from '@t-req/core';
+import { resolveProjectConfig } from '@t-req/core/config';
+${runtime === 'node' ? "import { createNodeIO } from '@t-req/core/runtime';" : ''}
+
+function getFlagValue(name: string): string | undefined {
+  const idx = process.argv.indexOf(name);
+  if (idx === -1) return undefined;
+  const value = process.argv[idx + 1];
+  return value && !value.startsWith('-') ? value : undefined;
+}
+
+const profile = getFlagValue('--profile') ?? process.env.TREQ_PROFILE;
+const { config, meta } = await resolveProjectConfig({
+  startDir: process.cwd(),
+  profile: profile || undefined,
+});
+
+for (const warning of meta.warnings) {
+  console.warn(\`Warning: \${warning}\`);
+}
 
 const client = createClient({
-  variables: {
-    baseUrl: 'https://jsonplaceholder.typicode.com',
-  },
+  ${runtime === 'node' ? 'io: createNodeIO(),' : ''}
+  variables: config.variables,
+  // Map config defaults into the client (timeout + headers/redirects/ssl/proxy).
+  timeout: config.defaults.timeoutMs,
+  defaults: config.defaults,
 });
 
 // Example: Get a user
@@ -298,36 +327,9 @@ dist/
 .env
 .env.local
 *.log
-`;
-}
-
-export function generateDevEnvironment(): string {
-  return `// Development environment
-export default {
-  baseUrl: 'http://localhost:3000',
-};
-`;
-}
-
-export function generateProdEnvironment(): string {
-  return `// Production environment
-export default {
-  baseUrl: 'https://api.example.com',
-};
-`;
-}
 
-export function generateFolderDefaults(): string {
-  return `// Folder defaults - requests in this folder inherit these settings
-export default {
-  auth: {
-    type: 'bearer',
-    token: '{{authToken}}',
-  },
-  headers: {
-    'X-Custom-Header': 'value',
-  },
-};
+# t-req local state
+.treq/cookies.json
 `;
 }