@agentuity/cli 1.0.5 → 1.0.7

package/src/cmd/cloud/env/env-diff.ts

@@ -0,0 +1,180 @@
+import * as tui from '../../../tui';
+import { maskSecret } from '../../../env-util';
+
+export interface EnvDiffEntry {
+	key: string;
+	/** The value from the "source" side (the side being pushed/pulled from) */
+	sourceValue: string;
+	/** The value from the "target" side (the side being overwritten), undefined if new */
+	targetValue?: string;
+	/** Whether the source side stores this as a secret */
+	sourceIsSecret: boolean;
+	/** Whether the target side stores this as a secret (undefined if new, i.e. no target) */
+	targetIsSecret?: boolean;
+}
+
+export interface EnvDiff {
+	newEntries: EnvDiffEntry[];
+	changedEntries: EnvDiffEntry[];
+	unchangedEntries: EnvDiffEntry[];
+}
+
+/**
+ * Compute diff between source and target env/secrets.
+ * "Source" is where values come from; "target" is what will be overwritten.
+ *
+ * For push: source=local, target=remote
+ * For pull: source=cloud, target=local
+ */
+export function computeEnvDiff(
+	sourceEnv: Record<string, string>,
+	sourceSecrets: Record<string, string>,
+	targetEnv: Record<string, string>,
+	targetSecrets: Record<string, string>
+): EnvDiff {
+	const newEntries: EnvDiffEntry[] = [];
+	const changedEntries: EnvDiffEntry[] = [];
+	const unchangedEntries: EnvDiffEntry[] = [];
+
+	// Check env vars
+	for (const key of Object.keys(sourceEnv)) {
+		const sourceValue = sourceEnv[key]!;
+		if (key in targetEnv) {
+			if (sourceValue === targetEnv[key]) {
+				unchangedEntries.push({
+					key,
+					sourceValue,
+					targetValue: targetEnv[key],
+					sourceIsSecret: false,
+					targetIsSecret: false,
+				});
+			} else {
+				changedEntries.push({
+					key,
+					sourceValue,
+					targetValue: targetEnv[key],
+					sourceIsSecret: false,
+					targetIsSecret: false,
+				});
+			}
+		} else if (key in targetSecrets) {
+			// Key exists but as a different type - treat as changed
+			changedEntries.push({
+				key,
+				sourceValue,
+				targetValue: targetSecrets[key],
+				sourceIsSecret: false,
+				targetIsSecret: true,
+			});
+		} else {
+			newEntries.push({ key, sourceValue, sourceIsSecret: false });
+		}
+	}
+
+	// Check secrets
+	for (const key of Object.keys(sourceSecrets)) {
+		const sourceValue = sourceSecrets[key]!;
+		if (key in targetSecrets) {
+			if (sourceValue === targetSecrets[key]) {
+				unchangedEntries.push({
+					key,
+					sourceValue,
+					targetValue: targetSecrets[key],
+					sourceIsSecret: true,
+					targetIsSecret: true,
+				});
+			} else {
+				changedEntries.push({
+					key,
+					sourceValue,
+					targetValue: targetSecrets[key],
+					sourceIsSecret: true,
+					targetIsSecret: true,
+				});
+			}
+		} else if (key in targetEnv) {
+			// Key exists but as a different type - treat as changed
+			changedEntries.push({
+				key,
+				sourceValue,
+				targetValue: targetEnv[key],
+				sourceIsSecret: true,
+				targetIsSecret: false,
+			});
+		} else {
+			newEntries.push({ key, sourceValue, sourceIsSecret: true });
+		}
+	}
+
+	return { newEntries, changedEntries, unchangedEntries };
+}
+
+function displayValue(value: string, isSecret: boolean): string {
+	return isSecret ? maskSecret(value) : value;
+}
+
+export interface DisplayEnvDiffOptions {
+	/** Label for the operation, shown in header. E.g. "push" or "pull" */
+	direction: 'push' | 'pull';
+}
+
+/**
+ * Display a diff view of env changes.
+ * In TTY mode, shows a rich color-coded diff.
+ * In non-TTY mode, shows simple text summary.
+ */
+export function displayEnvDiff(diff: EnvDiff, options: DisplayEnvDiffOptions): void {
+	const { direction } = options;
+
+	// Non-TTY: simple summary
+	if (!tui.isTTYLike()) {
+		if (diff.newEntries.length > 0) {
+			tui.info(
+				`New variables: ${diff.newEntries.length} (${diff.newEntries.map((e) => e.key).join(', ')})`
+			);
+		}
+		if (diff.changedEntries.length > 0) {
+			const verb = direction === 'push' ? 'overwritten remotely' : 'overwritten locally';
+			tui.warning(
+				`Variables that will be ${verb}: ${diff.changedEntries.length} (${diff.changedEntries.map((e) => e.key).join(', ')})`
+			);
+		}
+		if (diff.unchangedEntries.length > 0) {
+			tui.info(`Unchanged variables: ${diff.unchangedEntries.length}`);
+		}
+		return;
+	}
+
+	// TTY: rich diff view
+	tui.newline();
+	tui.info('Environment variable changes:');
+	tui.newline();
+
+	// Sort all entries by key for consistent display
+	const allEntries = [
+		...diff.newEntries.map((e) => ({ ...e, status: 'new' as const })),
+		...diff.changedEntries.map((e) => ({ ...e, status: 'changed' as const })),
+		...diff.unchangedEntries.map((e) => ({ ...e, status: 'unchanged' as const })),
+	].sort((a, b) => a.key.localeCompare(b.key));
+
+	for (const entry of allEntries) {
+		const typeLabel = entry.sourceIsSecret ? 'secret' : 'env';
+		const val = displayValue(entry.sourceValue, entry.sourceIsSecret);
+
+		if (entry.status === 'new') {
+			const line = `  ${tui.colorSuccess('+')} ${tui.bold(entry.key)}=${val} ${tui.colorMuted(`(new, ${typeLabel})`)}`;
+			process.stderr.write(line + '\n');
+		} else if (entry.status === 'changed') {
+			const oldVal = displayValue(entry.targetValue!, entry.targetIsSecret ?? false);
+			// For push: show "remote_old → local_new" (replacing remote with local)
+			// For pull: show "local_old → cloud_new" (replacing local with cloud)
+			const line = `  ${tui.colorWarning('~')} ${tui.bold(entry.key)}=${oldVal} → ${val} ${tui.colorMuted(`(changed, ${typeLabel})`)}`;
+			process.stderr.write(line + '\n');
+		} else {
+			const line = `  ${tui.colorMuted(`= ${entry.key}=${val} (unchanged, ${typeLabel})`)}`;
+			process.stderr.write(line + '\n');
+		}
+	}
+
+	tui.newline();
+}

package/src/cmd/cloud/env/pull.ts

@@ -2,13 +2,24 @@ import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { projectGet, orgEnvGet } from '@agentuity/server';
-import { findExistingEnvFile, readEnvFile, writeEnvFile, mergeEnvVars } from '../../../env-util';
+import {
+	findExistingEnvFile,
+	readEnvFile,
+	writeEnvFile,
+	mergeEnvVars,
+	splitEnvAndSecrets,
+	filterAgentuitySdkKeys,
+} from '../../../env-util';
 import { getCommand } from '../../../command-prefix';
 import { resolveOrgId, isOrgScope } from './org-util';
+import { computeEnvDiff, displayEnvDiff } from './env-diff';
 
 const EnvPullResponseSchema = z.object({
 	success: z.boolean().describe('Whether pull succeeded'),
 	pulled: z.number().describe('Number of items pulled'),
+	newCount: z.number().describe('Number of new variables added locally'),
+	changedCount: z.number().describe('Number of local variables overwritten'),
+	unchangedCount: z.number().describe('Number of unchanged variables'),
 	path: z.string().describe('Local file path where variables were saved'),
 	force: z.boolean().describe('Whether force mode was used'),
 	scope: z.enum(['project', 'org']).describe('The scope from which variables were pulled'),
@@ -41,13 +52,15 @@ export const pullSubcommand = createSubcommand({
 	async handler(ctx) {
 		const { opts, apiClient, project, projectDir, config } = ctx;
 		const useOrgScope = isOrgScope(opts?.org);
+		const forceMode = opts?.force ?? false;
 
 		// Require project context for local file operations
 		if (!projectDir) {
 			tui.fatal('Project context required. Run from a project directory.');
 		}
 
-		let cloudEnv: Record<string, string>;
+		let cloudEnvVars: Record<string, string> = {};
+		let cloudSecretVars: Record<string, string> = {};
 		let scope: 'project' | 'org';
 		let cloudApiKey: string | undefined;
 
@@ -62,7 +75,8 @@ export const pullSubcommand = createSubcommand({
 				}
 			);
 
-			cloudEnv = { ...orgData.env, ...orgData.secrets };
+			cloudEnvVars = orgData.env || {};
+			cloudSecretVars = orgData.secrets || {};
 			scope = 'org';
 			cloudApiKey = undefined; // Orgs don't have api_key
 		} else {
@@ -77,7 +91,8 @@ export const pullSubcommand = createSubcommand({
 				return projectGet(apiClient, { id: project.projectId, mask: false });
 			});
 
-			cloudEnv = { ...projectData.env, ...projectData.secrets };
+			cloudEnvVars = projectData.env || {};
+			cloudSecretVars = projectData.secrets || {};
 			scope = 'project';
 			cloudApiKey = projectData.api_key;
 		}
@@ -89,9 +104,43 @@ export const pullSubcommand = createSubcommand({
 		// Preserve local AGENTUITY_SDK_KEY
 		const localSdkKey = localEnv.AGENTUITY_SDK_KEY;
 
+		// Split local env for diff comparison (excluding AGENTUITY_ reserved keys)
+		const localForDiff = { ...localEnv };
+		delete localForDiff.AGENTUITY_SDK_KEY;
+		const filteredLocal = filterAgentuitySdkKeys(localForDiff);
+		const { env: localEnvVars, secrets: localSecretVars } = splitEnvAndSecrets(filteredLocal);
+
+		// Compute diff: cloud (source) → local (target)
+		const diff = computeEnvDiff(cloudEnvVars, cloudSecretVars, localEnvVars, localSecretVars);
+
+		// Display diff
+		displayEnvDiff(diff, { direction: 'pull' });
+
+		// If force mode and there are changes, prompt for confirmation
+		if (forceMode && diff.changedEntries.length > 0) {
+			const confirmed = await tui.confirm(
+				`${diff.changedEntries.length} local variable${diff.changedEntries.length !== 1 ? 's' : ''} will be overwritten. Continue?`,
+				true
+			);
+			if (!confirmed) {
+				tui.info('Pull cancelled');
+				return {
+					success: false,
+					pulled: 0,
+					newCount: 0,
+					changedCount: 0,
+					unchangedCount: 0,
+					path: targetEnvPath,
+					force: forceMode,
+					scope,
+				};
+			}
+		}
+
 		// Merge: cloud values override local if force=true, otherwise keep local
+		const cloudEnv = { ...cloudEnvVars, ...cloudSecretVars };
 		let mergedEnv: Record<string, string>;
-		if (opts?.force) {
+		if (forceMode) {
 			// Cloud values take priority
 			mergedEnv = mergeEnvVars(localEnv, cloudEnv);
 		} else {
@@ -122,15 +171,26 @@ export const pullSubcommand = createSubcommand({
 
 		const count = Object.keys(cloudEnv).length;
 		const scopeLabel = useOrgScope ? 'organization' : 'project';
-		tui.success(
-			`Pulled ${count} environment variable${count !== 1 ? 's' : ''} from ${scopeLabel} to ${targetEnvPath}`
-		);
+
+		// Update success message with diff counts
+		if (forceMode) {
+			tui.success(
+				`Pulled ${count} variable${count !== 1 ? 's' : ''} from ${scopeLabel} (${diff.newEntries.length} new, ${diff.changedEntries.length} updated, ${diff.unchangedEntries.length} unchanged)`
+			);
+		} else {
+			tui.success(
+				`Pulled ${count} variable${count !== 1 ? 's' : ''} from ${scopeLabel} (${diff.newEntries.length} new, ${diff.changedEntries.length} skipped, ${diff.unchangedEntries.length} unchanged)`
+			);
+		}
 
 		return {
 			success: true,
 			pulled: count,
+			newCount: diff.newEntries.length,
+			changedCount: forceMode ? diff.changedEntries.length : 0,
+			unchangedCount: diff.unchangedEntries.length,
 			path: targetEnvPath,
-			force: opts?.force ?? false,
+			force: forceMode,
 			scope,
 		};
 	},

package/src/cmd/cloud/env/push.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
-import { projectEnvUpdate, orgEnvUpdate } from '@agentuity/server';
+import { projectEnvUpdate, orgEnvUpdate, projectGet, orgEnvGet } from '@agentuity/server';
 import {
 	findExistingEnvFile,
 	readEnvFile,
@@ -11,14 +11,19 @@ import {
 } from '../../../env-util';
 import { getCommand } from '../../../command-prefix';
 import { resolveOrgId, isOrgScope } from './org-util';
+import { computeEnvDiff, displayEnvDiff } from './env-diff';
 
 const EnvPushResponseSchema = z.object({
 	success: z.boolean().describe('Whether push succeeded'),
 	pushed: z.number().describe('Number of items pushed'),
 	envCount: z.number().describe('Number of env vars pushed'),
 	secretCount: z.number().describe('Number of secrets pushed'),
+	newCount: z.number().describe('Number of new variables added'),
+	changedCount: z.number().describe('Number of existing variables overwritten'),
+	unchangedCount: z.number().describe('Number of unchanged variables'),
 	source: z.string().describe('Source file path'),
 	scope: z.enum(['project', 'org']).describe('The scope where variables were pushed'),
+	force: z.boolean().describe('Whether force mode was used'),
 });
 
 export const pushSubcommand = createSubcommand({
@@ -39,6 +44,7 @@ export const pushSubcommand = createSubcommand({
 				.union([z.boolean(), z.string()])
 				.optional()
 				.describe('push to organization level (use --org for default org)'),
+			force: z.boolean().default(false).describe('overwrite remote values without confirmation'),
 		}),
 		response: EnvPushResponseSchema,
 	},
@@ -59,6 +65,8 @@ export const pushSubcommand = createSubcommand({
 		// Filter out reserved AGENTUITY_ prefixed keys
 		const filteredEnv = filterAgentuitySdkKeys(localEnv);
 
+		const forceMode = opts?.force ?? false;
+
 		if (Object.keys(filteredEnv).length === 0) {
 			tui.warning('No variables to push');
 			return {
@@ -66,8 +74,12 @@ export const pushSubcommand = createSubcommand({
 				pushed: 0,
 				envCount: 0,
 				secretCount: 0,
+				newCount: 0,
+				changedCount: 0,
+				unchangedCount: 0,
 				source: envFilePath,
 				scope: useOrgScope ? ('org' as const) : ('project' as const),
+				force: forceMode,
 			};
 		}
 
@@ -93,6 +105,38 @@ export const pushSubcommand = createSubcommand({
 			// Organization scope
 			const orgId = await resolveOrgId(apiClient, config, opts!.org!);
 
+			// Fetch remote state to compute diff
+			const orgData = await tui.spinner('Fetching remote variables', () => {
+				return orgEnvGet(apiClient, { id: orgId, mask: false });
+			});
+
+			const diff = computeEnvDiff(env, secrets, orgData.env || {}, orgData.secrets || {});
+
+			displayEnvDiff(diff, { direction: 'push' });
+
+			// Prompt for confirmation if there are changes to existing variables
+			if (diff.changedEntries.length > 0 && !forceMode) {
+				const confirmed = await tui.confirm(
+					`${diff.changedEntries.length} existing variable${diff.changedEntries.length !== 1 ? 's' : ''} will be overwritten. Continue?`,
+					true
+				);
+				if (!confirmed) {
+					tui.info('Push cancelled');
+					return {
+						success: false,
+						pushed: 0,
+						envCount: 0,
+						secretCount: 0,
+						newCount: 0,
+						changedCount: 0,
+						unchangedCount: 0,
+						source: envFilePath,
+						scope: 'org' as const,
+						force: forceMode,
+					};
+				}
+			}
+
 			await tui.spinner('Pushing variables to organization', () => {
 				return orgEnvUpdate(apiClient, {
 					id: orgId,
@@ -106,7 +150,7 @@ export const pushSubcommand = createSubcommand({
 			const totalCount = envCount + secretCount;
 
 			tui.success(
-				`Pushed ${totalCount} variable${totalCount !== 1 ? 's' : ''} to organization (${envCount} env, ${secretCount} secret${secretCount !== 1 ? 's' : ''})`
+				`Pushed ${totalCount} variable${totalCount !== 1 ? 's' : ''} to organization (${diff.newEntries.length} new, ${diff.changedEntries.length} updated, ${diff.unchangedEntries.length} unchanged)`
 			);
 
 			return {
@@ -114,17 +158,58 @@ export const pushSubcommand = createSubcommand({
 				pushed: totalCount,
 				envCount,
 				secretCount,
+				newCount: diff.newEntries.length,
+				changedCount: diff.changedEntries.length,
+				unchangedCount: diff.unchangedEntries.length,
 				source: envFilePath,
 				scope: 'org' as const,
+				force: forceMode,
 			};
 		} else {
-			// Project scope (existing behavior)
+			// Project scope
 			if (!project) {
 				tui.fatal(
 					'Project context required. Run from a project directory or use --org for organization scope.'
 				);
 			}
 
+			// Fetch remote state to compute diff
+			const projectData = await tui.spinner('Fetching remote variables', () => {
+				return projectGet(apiClient, { id: project.projectId, mask: false });
+			});
+
+			const diff = computeEnvDiff(
+				env,
+				secrets,
+				projectData.env || {},
+				projectData.secrets || {}
+			);
+
+			displayEnvDiff(diff, { direction: 'push' });
+
+			// Prompt for confirmation if there are changes to existing variables
+			if (diff.changedEntries.length > 0 && !forceMode) {
+				const confirmed = await tui.confirm(
+					`${diff.changedEntries.length} existing variable${diff.changedEntries.length !== 1 ? 's' : ''} will be overwritten. Continue?`,
+					true
+				);
+				if (!confirmed) {
+					tui.info('Push cancelled');
+					return {
+						success: false,
+						pushed: 0,
+						envCount: 0,
+						secretCount: 0,
+						newCount: 0,
+						changedCount: 0,
+						unchangedCount: 0,
+						source: envFilePath,
+						scope: 'project' as const,
+						force: forceMode,
+					};
+				}
+			}
+
 			await tui.spinner('Pushing variables to cloud', () => {
 				return projectEnvUpdate(apiClient, {
 					id: project.projectId,
@@ -138,7 +223,7 @@ export const pushSubcommand = createSubcommand({
 			const totalCount = envCount + secretCount;
 
 			tui.success(
-				`Pushed ${totalCount} variable${totalCount !== 1 ? 's' : ''} to cloud (${envCount} env, ${secretCount} secret${secretCount !== 1 ? 's' : ''})`
+				`Pushed ${totalCount} variable${totalCount !== 1 ? 's' : ''} to cloud (${diff.newEntries.length} new, ${diff.changedEntries.length} updated, ${diff.unchangedEntries.length} unchanged)`
 			);
 
 			return {
@@ -146,8 +231,12 @@ export const pushSubcommand = createSubcommand({
 				pushed: totalCount,
 				envCount,
 				secretCount,
+				newCount: diff.newEntries.length,
+				changedCount: diff.changedEntries.length,
+				unchangedCount: diff.unchangedEntries.length,
 				source: envFilePath,
 				scope: 'project' as const,
+				force: forceMode,
 			};
 		}
 	},