@agentuity/cli 3.0.0-alpha.7 → 3.0.0-beta.0

package/src/runtime-bootstrap.md

@@ -1,160 +0,0 @@
-# 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/runtime';
-
-// 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/tests/integration/integration-suite/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/tests/integration/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.ts

@@ -1,36 +0,0 @@
-import { semver } from 'bun';
-
-const MIN_BUN_VERSION = '>=1.3.3';
-const MIN_GRAVITY_VERSION = '>=1.0.6';
-
-export function isBun(): boolean {
-	return typeof Bun !== 'undefined';
-}
-
-/**
- * Validate if you're running a compatible minimum version of Bun
- */
-export function validateRuntime(): void {
-	if (!isBun()) {
-		console.error('Error: This CLI requires Bun runtime');
-		console.error('Please install Bun: https://bun.sh');
-		process.exit(1);
-	}
-
-	const bunVersion = Bun.version;
-	if (semver.satisfies(bunVersion, MIN_BUN_VERSION) === false) {
-		console.error(`Error: This CLI requires Bun ${MIN_BUN_VERSION}`);
-		console.error(`Current Bun version: ${bunVersion}`);
-		process.exit(1);
-	}
-}
-
-/**
- * Returns true if the gravity binary requires an upgrade
- *
- * @param version current version
- * @returns
- */
-export function validateGravityRequiresUpgrade(version: string): boolean {
-	return semver.satisfies(version, MIN_GRAVITY_VERSION) === false;
-}

package/src/schema-generator.ts

@@ -1,443 +0,0 @@
-import type { Command } from 'commander';
-import type { CommandDefinition, SubcommandDefinition, CommandSchemas } from './types';
-import { exitCodeDescriptions } from './errors';
-import { parseArgsSchema, parseOptionsSchema } from './schema-parser';
-import * as z from 'zod';
-
-export interface SchemaArgument {
-	name: string;
-	type: string;
-	required: boolean;
-	variadic: boolean;
-	description?: string;
-}
-
-export interface SchemaOption {
-	name: string;
-	type: 'string' | 'number' | 'boolean' | 'array' | 'optionalString';
-	required: boolean;
-	default?: unknown;
-	description?: string;
-	enum?: string[];
-}
-
-export interface SchemaPagination {
-	supported: boolean;
-	defaultLimit?: number;
-	maxLimit?: number;
-	parameters?: {
-		limit?: string;
-		offset?: string;
-		cursor?: string;
-	};
-}
-
-export interface SchemaExample {
-	command: string;
-	description: string;
-}
-
-export interface SchemaCommand {
-	name: string;
-	description: string;
-	aliases?: string[];
-	arguments?: SchemaArgument[];
-	options?: SchemaOption[];
-	examples?: SchemaExample[];
-	response?: unknown;
-	idempotent?: boolean;
-	prerequisites?: string[];
-	pagination?: SchemaPagination;
-	tags?: string[];
-	skipSkill?: boolean;
-	toplevel?: boolean;
-	subcommands?: SchemaCommand[];
-	requires?: {
-		auth?: boolean;
-		project?: boolean;
-		org?: boolean;
-		region?: boolean;
-		regions?: boolean;
-	};
-	optional?: {
-		auth?: boolean | string;
-		project?: boolean;
-		org?: boolean;
-		region?: boolean;
-	};
-}
-
-export interface CLISchema {
-	name: string;
-	version: string;
-	description: string;
-	exitCodes: Record<number, string>;
-	globalOptions: SchemaOption[];
-	commands: SchemaCommand[];
-}
-
-/**
- * Apply args, options, and response from a CommandSchemas to a SchemaCommand.
- * Shared by both extractCommandSchema and extractSubcommandSchema.
- */
-function applySchemaFields(schema: SchemaCommand, schemas: CommandSchemas): void {
-	if (schemas.args) {
-		const parsedArgs = parseArgsSchema(schemas.args);
-		schema.arguments = parsedArgs.metadata.map((arg) => ({
-			name: arg.name,
-			type: arg.variadic ? 'array' : 'string',
-			required: !arg.optional,
-			variadic: arg.variadic,
-		}));
-	}
-
-	if (schemas.options) {
-		const parsedOptions = parseOptionsSchema(schemas.options);
-		schema.options = parsedOptions.map((opt) => ({
-			name: opt.name,
-			type: opt.type,
-			required: !opt.hasDefault,
-			default: opt.defaultValue,
-			description: opt.description,
-		}));
-	}
-
-	if (schemas.response) {
-		schema.response = z.toJSONSchema(schemas.response);
-	}
-}
-
-/**
- * Extract schema information from a CommandDefinition
- */
-export function extractCommandSchema(def: CommandDefinition): SchemaCommand {
-	const schema: SchemaCommand = {
-		name: def.name,
-		description: def.description,
-	};
-
-	if (def.aliases) {
-		schema.aliases = def.aliases;
-	}
-
-	// Extract examples if available
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).examples) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.examples = (def as any).examples;
-	}
-
-	// Extract idempotent marker
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).idempotent !== undefined) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.idempotent = (def as any).idempotent;
-	}
-
-	// Extract prerequisites
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).prerequisites) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.prerequisites = (def as any).prerequisites;
-	}
-
-	// Extract pagination
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).pagination) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.pagination = (def as any).pagination;
-	}
-
-	// Extract tags
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).tags) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.tags = (def as any).tags;
-	}
-
-	// Extract skipSkill
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).skipSkill !== undefined) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.skipSkill = (def as any).skipSkill;
-	}
-
-	// Extract requires/optional
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	const d = def as any;
-	if (d.requires) {
-		schema.requires = {
-			auth: d.requires.auth === true,
-			project: d.requires.project === true,
-			org: d.requires.org === true,
-			region: d.requires.region === true,
-			regions: d.requires.regions === true,
-		};
-	}
-	if (d.optional) {
-		schema.optional = {
-			auth: d.optional.auth === true || typeof d.optional.auth === 'string',
-			project: d.optional.project === true,
-			org: d.optional.org === true,
-			region: d.optional.region === true,
-		};
-	}
-
-	// Extract args and options from schema if available
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).schema) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		const schemas = (def as any).schema as CommandSchemas;
-		applySchemaFields(schema, schemas);
-	}
-
-	// Extract subcommands recursively
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).subcommands) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.subcommands = ((def as any).subcommands as SubcommandDefinition[]).map((sub) =>
-			extractSubcommandSchema(sub)
-		);
-	}
-
-	return schema;
-}
-
-/**
- * Extract schema information from a SubcommandDefinition
- */
-export function extractSubcommandSchema(def: SubcommandDefinition): SchemaCommand {
-	const schema: SchemaCommand = {
-		name: def.name,
-		description: def.description,
-	};
-
-	if (def.aliases) {
-		schema.aliases = def.aliases;
-	}
-
-	// Extract examples if available
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).examples) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.examples = (def as any).examples;
-	}
-
-	// Extract idempotent marker
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).idempotent !== undefined) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.idempotent = (def as any).idempotent;
-	}
-
-	// Extract prerequisites
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).prerequisites) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.prerequisites = (def as any).prerequisites;
-	}
-
-	// Extract pagination
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).pagination) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.pagination = (def as any).pagination;
-	}
-
-	// Extract tags
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).tags) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.tags = (def as any).tags;
-	}
-
-	// Extract skipSkill
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).skipSkill !== undefined) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.skipSkill = (def as any).skipSkill;
-	}
-
-	// Extract toplevel
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	if ((def as any).toplevel !== undefined) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		schema.toplevel = (def as any).toplevel;
-	}
-
-	// Extract requires/optional
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	const d = def as any;
-	if (d.requires) {
-		schema.requires = {
-			auth: d.requires.auth === true,
-			project: d.requires.project === true,
-			org: d.requires.org === true,
-			region: d.requires.region === true,
-			regions: d.requires.regions === true,
-		};
-	}
-	if (d.optional) {
-		schema.optional = {
-			auth: d.optional.auth === true || typeof d.optional.auth === 'string',
-			project: d.optional.project === true,
-			org: d.optional.org === true,
-			region: d.optional.region === true,
-		};
-	}
-
-	// Extract args and options from schema if available
-	if (d.schema) {
-		const schemas = d.schema as CommandSchemas;
-		applySchemaFields(schema, schemas);
-	}
-
-	// Extract nested subcommands recursively
-	if (d.subcommands) {
-		schema.subcommands = (d.subcommands as SubcommandDefinition[]).map((sub) =>
-			extractSubcommandSchema(sub)
-		);
-	}
-
-	return schema;
-}
-
-/**
- * Generate JSON schema for the entire CLI
- */
-export function generateCLISchema(
-	_program: Command,
-	commands: CommandDefinition[],
-	version: string
-): CLISchema {
-	const schema: CLISchema = {
-		name: 'agentuity',
-		version,
-		description: 'Agentuity CLI',
-		exitCodes: { ...exitCodeDescriptions },
-		globalOptions: [
-			{
-				name: 'config',
-				type: 'string',
-				required: false,
-				description: 'Config file path',
-			},
-			{
-				name: 'log-level',
-				type: 'string',
-				required: false,
-				default: 'info',
-				description: 'Log level',
-				enum: ['debug', 'trace', 'info', 'warn', 'error'],
-			},
-			{
-				name: 'log-timestamp',
-				type: 'boolean',
-				required: false,
-				default: false,
-				description: 'Show timestamps in log output',
-			},
-			{
-				name: 'log-prefix',
-				type: 'boolean',
-				required: false,
-				default: true,
-				description: 'Show log level prefixes',
-			},
-			{
-				name: 'org-id',
-				type: 'string',
-				required: false,
-				description: 'Use a specific organization when performing operations (alias: --org)',
-			},
-			{
-				name: 'color-scheme',
-				type: 'string',
-				required: false,
-				description: 'Color scheme: light or dark',
-				enum: ['light', 'dark'],
-			},
-			{
-				name: 'color',
-				type: 'string',
-				required: false,
-				default: 'auto',
-				description: 'Color output: auto, always, never',
-				enum: ['auto', 'always', 'never'],
-			},
-			{
-				name: 'error-format',
-				type: 'string',
-				required: false,
-				default: 'text',
-				description: 'Error output format: json or text',
-				enum: ['json', 'text'],
-			},
-			{
-				name: 'json',
-				type: 'boolean',
-				required: false,
-				default: false,
-				description: 'Output in JSON format (machine-readable)',
-			},
-			{
-				name: 'quiet',
-				type: 'boolean',
-				required: false,
-				default: false,
-				description: 'Suppress non-essential output',
-			},
-			{
-				name: 'no-progress',
-				type: 'boolean',
-				required: false,
-				default: false,
-				description: 'Disable progress indicators',
-			},
-			{
-				name: 'explain',
-				type: 'boolean',
-				required: false,
-				default: false,
-				description: 'Show what the command would do without executing',
-			},
-			{
-				name: 'dry-run',
-				type: 'boolean',
-				required: false,
-				default: false,
-				description: 'Execute command without making changes',
-			},
-			{
-				name: 'validate',
-				type: 'boolean',
-				required: false,
-				default: false,
-				description: 'Validate arguments and options without executing',
-			},
-			{
-				name: 'input',
-				type: 'string',
-				required: false,
-				description: 'Pass arguments and options as a JSON object (for agents)',
-			},
-			{
-				name: 'describe',
-				type: 'boolean',
-				required: false,
-				default: false,
-				description: 'Output command schema as JSON for agent introspection',
-			},
-			{
-				name: 'fields',
-				type: 'string',
-				required: false,
-				description:
-					'Filter JSON output to specified fields (comma-separated, dot notation for nested)',
-			},
-		],
-		commands: commands.map(extractCommandSchema),
-	};
-
-	return schema;
-}