@agentuity/cli 0.0.92 → 0.0.94

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,
+	};
+}

package/src/tui.ts

@@ -307,7 +307,7 @@ export function link(url: string, title?: string, color = getColor('link')): str
 /**
  * Check if terminal supports OSC 8 hyperlinks
  */
-function supportsHyperlinks(): boolean {
+export function supportsHyperlinks(): boolean {
 	const term = process.env.TERM || '';
 	const termProgram = process.env.TERM_PROGRAM || '';
 	const wtSession = process.env.WT_SESSION || '';
@@ -361,7 +361,7 @@ export function output(message: string): void {
  * which causes incorrect alignment. We strip OSC 8 codes first, then use Bun.stringWidth()
  * to handle regular ANSI codes and unicode characters correctly.
  */
-function getDisplayWidth(str: string): number {
+export function getDisplayWidth(str: string): number {
 	// Remove OSC-8 hyperlink sequences using Unicode escapes (\u001b = ESC, \u0007 = BEL) to satisfy linter
 	// eslint-disable-next-line no-control-regex
 	const withoutOSC8 = str.replace(/\u001b\]8;;[^\u0007]*\u0007/g, '');
@@ -371,7 +371,7 @@ function getDisplayWidth(str: string): number {
 /**
  * Strip all ANSI escape sequences from a string
  */
-function stripAnsi(str: string): string {
+export function stripAnsi(str: string): string {
 	// eslint-disable-next-line no-control-regex
 	return str.replace(/\u001b\[[0-9;]*m/g, '').replace(/\u001b\]8;;[^\u0007]*\u0007/g, '');
 }

package/src/version-check.ts

@@ -1,6 +1,6 @@
 import type { Config, Logger, CommandDefinition } from './types';
 import { isRunningFromExecutable, fetchLatestVersion } from './cmd/upgrade';
-import { getVersion } from './version';
+import { getVersion, getCompareUrl, getReleaseUrl, toTag } from './version';
 import * as tui from './tui';
 import { saveConfig } from './config';
 import { $ } from 'bun';
@@ -97,6 +97,11 @@ async function promptUpgrade(currentVersion: string, latestVersion: string): Pro
 	tui.info(`Current version: ${tui.muted(currentVersion)}`);
 	tui.info(`Latest version:  ${tui.bold(latestVersion)}`);
 	tui.newline();
+	if (toTag(currentVersion) !== toTag(latestVersion)) {
+		tui.warning(`What's changed:  ${tui.link(getCompareUrl(currentVersion, latestVersion))}`);
+	}
+	tui.success(`Release notes:   ${tui.link(getReleaseUrl(latestVersion))}`);
+	tui.newline();
 
 	return await tui.confirm('Would you like to upgrade now?', true);
 }

package/src/version.ts

@@ -27,3 +27,31 @@ export function getRevision(): string {
 	// Bun provides git SHA via Bun.revision
 	return typeof Bun !== 'undefined' && Bun.revision ? Bun.revision.substring(0, 8) : 'unknown';
 }
+
+const GITHUB_REPO_URL = 'https://github.com/agentuity/sdk';
+
+/**
+ * Normalize a version string to a Git tag format (with 'v' prefix)
+ */
+export function toTag(version: string): string {
+	return version.startsWith('v') ? version : `v${version}`;
+}
+
+/**
+ * Get the GitHub URL for comparing two versions
+ * @param fromVersion - The current/old version
+ * @param toVersion - The new/target version
+ * @returns GitHub compare URL
+ */
+export function getCompareUrl(fromVersion: string, toVersion: string): string {
+	return `${GITHUB_REPO_URL}/compare/${toTag(fromVersion)}...${toTag(toVersion)}`;
+}
+
+/**
+ * Get the GitHub URL for a specific release
+ * @param version - The version to get the release URL for
+ * @returns GitHub release URL
+ */
+export function getReleaseUrl(version: string): string {
+	return `${GITHUB_REPO_URL}/releases/tag/${toTag(version)}`;
+}