@agentuity/cli 0.0.93 → 0.0.95

package/src/index.ts

@@ -75,6 +75,11 @@ export { showBanner } from './banner';
 export { discoverCommands } from './cmd';
 export { detectColorScheme } from './terminal';
 export { getCommandPrefix, getCommand } from './command-prefix';
+export {
+	bootstrapRuntimeEnv,
+	type RuntimeBootstrapOptions,
+	type RuntimeBootstrapResult,
+} from './runtime-bootstrap';
 export * as tui from './tui';
 export {
 	createRepl,

package/src/runtime-bootstrap.md

@@ -0,0 +1,161 @@
+# Runtime Bootstrap Utility
+
+## Problem
+
+When running SDK test applications locally (integration-suite, cloud-deployment), they weren't respecting:
+
+- Profile-specific `.env` files (`.env.local`, `.env.production`)
+- Profile-specific config files (`agentuity.local.json`, `agentuity.production.json`)
+
+This caused tests to fail because:
+
+1. `AGENTUITY_SDK_KEY` wasn't loaded from `.env.local`
+2. `AGENTUITY_REGION` wasn't set to `local` for local profile
+3. Services tried to connect to production URLs instead of `*.agentuity.io`
+
+## Solution
+
+The `bootstrapRuntimeEnv()` function loads profile-aware configuration and environment variables **before** `createApp()` is called.
+
+### What it does:
+
+1. **Resolves active profile** via `loadConfig()`
+   - Checks `AGENTUITY_PROFILE` env var
+   - Reads `~/.config/agentuity/profile` file
+   - Falls back to `production` profile
+
+2. **Loads `.env` files** based on profile:
+   - For `local` profile: `.env.local`, `.env.development`, `.env`
+   - For `production` profile: `.env.production`, `.env`
+
+3. **Sets environment variables**:
+   - Only sets if not already defined (existing env wins)
+   - For `local` profile: defaults `AGENTUITY_REGION=local`
+   - Sets `AGENTUITY_PROFILE` to match active profile
+
+4. **Loads project config**:
+   - For `local` profile: `agentuity.local.json`
+   - For `production` profile: `agentuity.json` or `agentuity.production.json`
+
+### Usage
+
+Call `bootstrapRuntimeEnv()` at the top of your `app.ts` **before** `createApp()`:
+
+```ts
+import { createApp } from '@agentuity/runtime';
+import { bootstrapRuntimeEnv } from '@agentuity/cli';
+
+// Bootstrap runtime environment based on active profile
+await bootstrapRuntimeEnv();
+
+// Now createApp() will use the correct env vars
+const app = await createApp();
+```
+
+### Options
+
+```ts
+await bootstrapRuntimeEnv({
+	projectDir: '/path/to/project', // default: process.cwd()
+	profile: 'local', // override active profile
+});
+```
+
+### Local Development Setup
+
+To run tests locally with local services:
+
+1. **Create local profile** (if not exists):
+
+   ```bash
+   cd ~/.config/agentuity
+   touch local.yaml
+   echo "name: local" > local.yaml
+   ```
+
+2. **Select local profile**:
+
+   ```bash
+   agentuity profile switch local
+   # Or set env var:
+   export AGENTUITY_PROFILE=local
+   ```
+
+3. **Create `.env.local`** in project root:
+
+   ```bash
+   AGENTUITY_SDK_KEY=your-sdk-key-here
+   AGENTUITY_REGION=local  # Optional, auto-set for local profile
+   ```
+
+4. **(Optional) Create `agentuity.local.json`** for project-specific overrides:
+   ```json
+   {
+   	"projectId": "proj_local_test",
+   	"orgId": "org_local",
+   	"region": "local"
+   }
+   ```
+
+### How it works
+
+The bootstrap process follows this precedence (highest to lowest):
+
+1. **Explicit env vars** (from shell/CI) - always wins
+2. **Profile-specific .env** (`.env.local` for local profile)
+3. **Development/production .env** (`.env.development` or `.env.production`)
+4. **Default .env** (`.env`)
+
+For config files:
+
+1. **Profile-specific config** (`agentuity.local.json` for local profile)
+2. **Default config** (`agentuity.json`)
+
+### Integration Points
+
+This utility is used by:
+
+- `sdk/apps/testing/integration-suite/app.ts`
+- `sdk/apps/testing/cloud-deployment/app.ts`
+
+It reuses existing infrastructure from the CLI:
+
+- `loadConfig()` - Resolves active profile
+- `loadProjectConfig()` - Loads profile-specific project config
+- `getEnvFilePaths()` - Determines which .env files to load
+- `readEnvFile()` - Parses .env files
+
+### Design Decisions
+
+**Why not embed in `createApp()`?**
+
+- `createApp()` is a runtime primitive that should work in any environment
+- CLI config and profile logic is Bun-specific
+- Test harnesses can opt-in to this behavior without forcing it on all SDK users
+
+**Why not auto-detect local vs production?**
+
+- Profile system is the single source of truth
+- `NODE_ENV` alone is insufficient (can be `development` in production)
+- Region alone is insufficient (multiple regions, not just local vs cloud)
+- Profile explicitly declares intent: "I want local services"
+
+### Testing
+
+To verify it works:
+
+```bash
+# Set local profile
+export AGENTUITY_PROFILE=local
+
+# Build and run
+cd sdk/apps/testing/integration-suite
+bun run build
+cd .agentuity && bun run app.js
+
+# Check logs for:
+# [TEST-SUITE] Profile: local
+# [TEST-SUITE] Region: local
+```
+
+Services should connect to `*.agentuity.io` instead of `*.agentuity.cloud`.

package/src/runtime-bootstrap.ts

@@ -0,0 +1,125 @@
+/**
+ * Runtime environment bootstrapping utility
+ *
+ * Loads configuration and environment variables based on the active profile
+ * before createApp() is called. This ensures .env.{profile} files and
+ * agentuity.{profile}.json configs are respected.
+ */
+
+import { loadConfig, loadProjectConfig } from './config';
+import { getEnvFilePaths, readEnvFile, type EnvVars } from './env-util';
+import type { Config, ProjectConfig } from './types';
+
+export interface RuntimeBootstrapOptions {
+	/**
+	 * Project directory containing agentuity.json and .env files
+	 * @default process.cwd()
+	 */
+	projectDir?: string;
+
+	/**
+	 * Override the active profile (otherwise uses loadConfig())
+	 */
+	profile?: string;
+}
+
+export interface RuntimeBootstrapResult {
+	/**
+	 * Resolved CLI config (from ~/.config/agentuity/)
+	 */
+	config: Config | null;
+
+	/**
+	 * Resolved project config (agentuity.json or agentuity.{profile}.json)
+	 */
+	projectConfig: ProjectConfig | null;
+}
+
+/**
+ * Bootstrap runtime environment by loading profile-aware config and env files.
+ *
+ * This function:
+ * 1. Resolves the active profile (from AGENTUITY_PROFILE env or profile config)
+ * 2. Loads .env.{profile}, .env.development, or .env based on profile
+ * 3. Sets AGENTUITY_REGION=local for local profile
+ * 4. Loads agentuity.{profile}.json if it exists
+ * 5. Does NOT override environment variables already set
+ *
+ * Call this BEFORE createApp() in your app.ts:
+ *
+ * @example
+ * ```ts
+ * import { bootstrapRuntimeEnv } from '@agentuity/cli/runtime-bootstrap';
+ * import { createApp } from '@agentuity/runtime';
+ *
+ * // Load config and env based on active profile
+ * await bootstrapRuntimeEnv();
+ *
+ * // Now createApp() will use the correct env vars
+ * const app = await createApp();
+ * ```
+ */
+export async function bootstrapRuntimeEnv(
+	options: RuntimeBootstrapOptions = {}
+): Promise<RuntimeBootstrapResult> {
+	const projectDir = options.projectDir || process.cwd();
+
+	// Load CLI config to determine active profile
+	let cfg: Config | null = null;
+	try {
+		cfg = await loadConfig();
+		// Override profile if specified
+		if (options.profile) {
+			cfg = { ...cfg, name: options.profile };
+		}
+	} catch {
+		// No config found - OK for tests without CLI setup
+	}
+
+	// Determine which .env files to load based on profile
+	const isProduction = process.env.NODE_ENV === 'production';
+	const envPaths = getEnvFilePaths(projectDir, {
+		configName: cfg?.name,
+		isProduction,
+	});
+
+	// Load and merge env files (later files override earlier ones)
+	let fileEnv: EnvVars = {};
+	for (const path of envPaths) {
+		const vars = await readEnvFile(path);
+		// Later files override earlier ones
+		fileEnv = { ...fileEnv, ...vars };
+	}
+
+	// Apply to process.env ONLY if not already set
+	// This ensures existing env vars (from shell/CI) always win
+	for (const [key, value] of Object.entries(fileEnv)) {
+		if (process.env[key] === undefined) {
+			process.env[key] = value;
+		}
+	}
+
+	// For local profile, default AGENTUITY_REGION to 'local'
+	// This makes getServiceUrls() use *.agentuity.io instead of *.agentuity.cloud
+	if (cfg?.name === 'local' && !process.env.AGENTUITY_REGION) {
+		process.env.AGENTUITY_REGION = 'local';
+	}
+
+	// Propagate profile name into env for consistency
+	if (cfg?.name && !process.env.AGENTUITY_PROFILE) {
+		process.env.AGENTUITY_PROFILE = cfg.name;
+	}
+
+	// Load project config (agentuity.json or agentuity.{profile}.json)
+	let projectConfig: ProjectConfig | null = null;
+	try {
+		projectConfig = await loadProjectConfig(projectDir, cfg ?? undefined);
+	} catch {
+		// OK for tests that don't need project config
+	}
+
+	return {
+		config: cfg,
+		projectConfig,
+	};
+}