@agentuity/cli 0.0.101 → 0.0.103

package/src/cmd/cloud/vector/index.ts

@@ -1,22 +1,39 @@
 import { createCommand } from '../../../types';
 import { deleteSubcommand } from './delete';
+import { deleteNamespaceSubcommand } from './delete-namespace';
 import { getSubcommand } from './get';
+import { listNamespacesSubcommand } from './list-namespaces';
 import { searchSubcommand } from './search';
+import { statsSubcommand } from './stats';
+import { upsertSubcommand } from './upsert';
 import { getCommand } from '../../../command-prefix';
 
 export const vectorCommand = createCommand({
 	name: 'vector',
 	aliases: ['vec'],
 	description: 'Manage vector storage for your projects',
-	tags: ['requires-auth', 'destructive', 'deletes-resource', 'slow'],
+	tags: ['requires-auth', 'slow'],
 	examples: [
 		{
-			command: getCommand('cloud vector search "query text"'),
+			command: getCommand('cloud vector search products "query text"'),
 			description: 'Search vector storage',
 		},
-		{ command: getCommand('cloud vec get <id>'), description: 'Get vector by ID' },
+		{
+			command: getCommand('cloud vec upsert products doc1 --document "text"'),
+			description: 'Upsert a vector',
+		},
+		{ command: getCommand('cloud vec get products doc1'), description: 'Get vector by key' },
+		{ command: getCommand('cloud vec stats'), description: 'Show namespace statistics' },
+	],
+	subcommands: [
+		upsertSubcommand,
+		searchSubcommand,
+		getSubcommand,
+		deleteSubcommand,
+		statsSubcommand,
+		listNamespacesSubcommand,
+		deleteNamespaceSubcommand,
 	],
-	subcommands: [searchSubcommand, getSubcommand, deleteSubcommand],
 	requires: { auth: true, project: true },
 });
 

package/src/cmd/cloud/vector/list-namespaces.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../../command-prefix';
+
+const NamespaceListResponseSchema = z.array(z.string().describe('Namespace name'));
+
+export const listNamespacesSubcommand = createCommand({
+	name: 'list-namespaces',
+	aliases: ['namespaces', 'ns'],
+	description: 'List all vector namespaces',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, project: true },
+	examples: [
+		{ command: getCommand('vector list-namespaces'), description: 'List all namespaces' },
+		{ command: getCommand('vector namespaces'), description: 'List namespaces (using alias)' },
+		{ command: getCommand('vector ns'), description: 'List namespaces (short alias)' },
+	],
+	schema: {
+		response: NamespaceListResponseSchema,
+	},
+	webUrl: '/services/vector',
+	idempotent: true,
+
+	async handler(ctx) {
+		const { options } = ctx;
+		const storage = await createStorageAdapter(ctx);
+		const namespaces = await storage.getNamespaces();
+
+		if (!options.json) {
+			if (namespaces.length === 0) {
+				tui.info('No vector namespaces found');
+			} else {
+				tui.info(`Found ${namespaces.length} namespace(s):`);
+				for (const name of namespaces) {
+					tui.arrow(name);
+				}
+			}
+		}
+
+		return namespaces;
+	},
+});
+
+export default listNamespacesSubcommand;

package/src/cmd/cloud/vector/stats.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../../command-prefix';
+
+const VectorItemStatsSchema = z.object({
+	embedding: z.array(z.number()).optional().describe('The embedding vector'),
+	document: z.string().optional().describe('Original document text'),
+	size: z.number().describe('Size in bytes'),
+	metadata: z.record(z.string(), z.unknown()).optional().describe('Metadata'),
+	firstUsed: z.number().describe('First access timestamp (ms)'),
+	lastUsed: z.number().describe('Last access timestamp (ms)'),
+	count: z.number().optional().describe('Access count (only available in cloud storage)'),
+});
+
+const VectorNamespaceStatsSchema = z.object({
+	sum: z.number().describe('Total size in bytes'),
+	count: z.number().describe('Number of vectors'),
+	createdAt: z.number().optional().describe('Creation timestamp (ms)'),
+	lastUsed: z.number().optional().describe('Last used timestamp (ms)'),
+});
+
+const VectorStatsResponseSchema = z.union([
+	VectorNamespaceStatsSchema.extend({
+		namespace: z.string().describe('Namespace name'),
+		sampledResults: z.record(z.string(), VectorItemStatsSchema).optional(),
+	}),
+	z.record(z.string(), VectorNamespaceStatsSchema),
+]);
+
+export const statsSubcommand = createCommand({
+	name: 'stats',
+	description: 'Get statistics for vector storage',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, project: true },
+	idempotent: true,
+	examples: [
+		{ command: getCommand('vector stats'), description: 'Show stats for all namespaces' },
+		{
+			command: getCommand('vector stats products'),
+			description: 'Show detailed stats for products namespace',
+		},
+		{ command: getCommand('vector stats embeddings'), description: 'Show stats for embeddings' },
+	],
+	schema: {
+		args: z.object({
+			name: z.string().optional().describe('the vector namespace (optional)'),
+		}),
+		response: VectorStatsResponseSchema,
+	},
+	webUrl: (ctx) =>
+		ctx.args.name ? `/services/vector/${encodeURIComponent(ctx.args.name)}` : '/services/vector',
+
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const storage = await createStorageAdapter(ctx);
+
+		if (args.name) {
+			const stats = await storage.getStats(args.name);
+
+			if (!options.json) {
+				if (stats.count === 0 && stats.sum === 0) {
+					tui.info(`Namespace ${tui.bold(args.name)} is empty or does not exist`);
+				} else {
+					tui.info(`Statistics for ${tui.bold(args.name)}:`);
+					tui.info(`  Vectors: ${stats.count}`);
+					const sizeDisplay =
+						stats.sum < 1024 * 1024
+							? `${stats.sum.toLocaleString()} bytes`
+							: `${(stats.sum / (1024 * 1024)).toFixed(2)} MB`;
+					tui.info(`  Total size: ${sizeDisplay}`);
+
+					if (stats.createdAt) {
+						tui.info(`  Created: ${new Date(stats.createdAt).toLocaleString()}`);
+					}
+					if (stats.lastUsed) {
+						tui.info(`  Last used: ${new Date(stats.lastUsed).toLocaleString()}`);
+					}
+
+					if (stats.sampledResults && Object.keys(stats.sampledResults).length > 0) {
+						tui.info('');
+						tui.info(`  Sample vectors (${Object.keys(stats.sampledResults).length}):`);
+
+						const tableData = Object.entries(stats.sampledResults).map(([key, item]) => {
+							const docPreview = item.document
+								? item.document.length > 30
+									? item.document.substring(0, 27) + '...'
+									: item.document
+								: '-';
+							return {
+								Key: key,
+								Size: `${item.size} bytes`,
+								Accesses: item.count ?? '-',
+								'Last Used': new Date(item.lastUsed).toLocaleDateString(),
+								Document: docPreview,
+							};
+						});
+
+						tui.table(tableData, [
+							{ name: 'Key', alignment: 'left' },
+							{ name: 'Size', alignment: 'right' },
+							{ name: 'Accesses', alignment: 'right' },
+							{ name: 'Last Used', alignment: 'left' },
+							{ name: 'Document', alignment: 'left' },
+						]);
+					}
+				}
+			}
+
+			return {
+				namespace: args.name,
+				...stats,
+			};
+		} else {
+			const allStats = await storage.getAllStats();
+			const entries = Object.entries(allStats);
+
+			if (!options.json) {
+				if (entries.length === 0) {
+					tui.info('No vector namespaces found');
+				} else {
+					tui.info(
+						`Found ${entries.length} ${tui.plural(entries.length, 'namespace', 'namespaces')}:`
+					);
+
+					const tableData = entries.map(([name, stats]) => {
+						const sizeDisplay =
+							stats.sum < 1024 * 1024
+								? `${stats.sum.toLocaleString()} bytes`
+								: `${(stats.sum / (1024 * 1024)).toFixed(2)} MB`;
+						return {
+							Namespace: name,
+							Vectors: stats.count,
+							Size: sizeDisplay,
+							Created: stats.createdAt
+								? new Date(stats.createdAt).toLocaleDateString()
+								: '-',
+							'Last Used': stats.lastUsed
+								? new Date(stats.lastUsed).toLocaleDateString()
+								: '-',
+						};
+					});
+
+					tui.table(tableData, [
+						{ name: 'Namespace', alignment: 'left' },
+						{ name: 'Vectors', alignment: 'right' },
+						{ name: 'Size', alignment: 'right' },
+						{ name: 'Created', alignment: 'left' },
+						{ name: 'Last Used', alignment: 'left' },
+					]);
+				}
+			}
+
+			return allStats;
+		}
+	},
+});
+
+export default statsSubcommand;

package/src/cmd/cloud/vector/upsert.ts

@@ -0,0 +1,216 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../../command-prefix';
+import type { VectorUpsertParams } from '@agentuity/core';
+
+const VectorUpsertResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	namespace: z.string().describe('Namespace name'),
+	count: z.number().describe('Number of vectors upserted'),
+	results: z
+		.array(
+			z.object({
+				key: z.string().describe('Vector key'),
+				id: z.string().describe('Vector ID'),
+			})
+		)
+		.describe('Upsert results with key-to-id mappings'),
+	durationMs: z.number().describe('Operation duration in milliseconds'),
+});
+
+export const upsertSubcommand = createCommand({
+	name: 'upsert',
+	aliases: ['put', 'add'],
+	description: 'Add or update vectors in the vector storage',
+	tags: ['mutating', 'updates-resource', 'slow', 'requires-auth'],
+	idempotent: true,
+	requires: { auth: true, project: true },
+	examples: [
+		{
+			command: getCommand('vector upsert products doc1 --document "Comfortable office chair"'),
+			description: 'Upsert a single vector with document text',
+		},
+		{
+			command: getCommand(
+				'vector upsert products doc1 --document "Chair" --metadata \'{"category":"furniture"}\''
+			),
+			description: 'Upsert with metadata',
+		},
+		{
+			command: getCommand('vector upsert embeddings vec1 --embeddings "[0.1, 0.2, 0.3]"'),
+			description: 'Upsert with pre-computed embeddings',
+		},
+		{
+			command: getCommand('vector upsert products --file vectors.json'),
+			description: 'Bulk upsert from JSON file',
+		},
+		{
+			command: `cat vectors.json | ${getCommand('vector upsert products -')}`,
+			description: 'Bulk upsert from stdin',
+		},
+	],
+	schema: {
+		args: z.object({
+			namespace: z.string().min(1).describe('the vector storage namespace'),
+			key: z
+				.string()
+				.optional()
+				.describe('the key for single vector upsert (not used with --file or stdin)'),
+		}),
+		options: z.object({
+			document: z.string().optional().describe('document text to embed'),
+			embeddings: z.string().optional().describe('pre-computed embeddings as JSON array'),
+			metadata: z.string().optional().describe('metadata as JSON object'),
+			file: z
+				.string()
+				.optional()
+				.describe('path to JSON file containing vectors, or "-" for stdin'),
+		}),
+		response: VectorUpsertResponseSchema,
+	},
+	webUrl: (ctx) => `/services/vector/${encodeURIComponent(ctx.args.namespace)}`,
+
+	async handler(ctx) {
+		const { args, opts, options, logger } = ctx;
+		const storage = await createStorageAdapter(ctx);
+
+		let documents: VectorUpsertParams[] = [];
+
+		// Check if reading from file or stdin
+		const fileArg = opts.file || (args.key === '-' ? '-' : undefined);
+
+		if (fileArg) {
+			let content: string;
+
+			if (fileArg === '-') {
+				// Read from stdin
+				const chunks: Uint8Array[] = [];
+				const reader = Bun.stdin.stream().getReader();
+
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					chunks.push(value);
+				}
+
+				const decoder = new TextDecoder();
+				content = chunks.map((chunk) => decoder.decode(chunk, { stream: true })).join('');
+			} else {
+				// Read from file
+				const file = Bun.file(fileArg);
+				if (!(await file.exists())) {
+					tui.fatal(`File not found: ${fileArg}`);
+				}
+				content = await file.text();
+			}
+
+			try {
+				const parsed = JSON.parse(content.trim());
+				if (Array.isArray(parsed)) {
+					documents = parsed as VectorUpsertParams[];
+				} else {
+					documents = [parsed as VectorUpsertParams];
+				}
+			} catch {
+				tui.fatal('Invalid JSON in input file/stdin');
+			}
+
+			// Validate documents
+			for (const doc of documents) {
+				if (!doc.key || typeof doc.key !== 'string') {
+					tui.fatal('Each document must have a non-empty "key" property');
+				}
+				if (!doc.document && !('embeddings' in doc)) {
+					tui.fatal(
+						`Document with key "${doc.key}" must have either "document" or "embeddings" property`
+					);
+				}
+			}
+		} else {
+			// Single vector upsert via command line arguments
+			if (!args.key) {
+				tui.fatal('Key is required for single vector upsert. Use --file for bulk upsert.');
+			}
+
+			if (!opts.document && !opts.embeddings) {
+				tui.fatal('Either --document or --embeddings is required');
+			}
+
+			if (opts.document && opts.embeddings) {
+				tui.fatal('Cannot use both --document and --embeddings');
+			}
+
+			let metadata: Record<string, unknown> | undefined;
+			if (opts.metadata) {
+				try {
+					metadata = JSON.parse(opts.metadata);
+				} catch {
+					tui.fatal('Invalid JSON in --metadata');
+				}
+			}
+
+			if (opts.document) {
+				documents = [
+					{
+						key: args.key,
+						document: opts.document,
+						metadata,
+					},
+				];
+			} else if (opts.embeddings) {
+				let embeddings: number[];
+				try {
+					embeddings = JSON.parse(opts.embeddings);
+					if (!Array.isArray(embeddings) || !embeddings.every((n) => typeof n === 'number')) {
+						throw new Error('Not an array of numbers');
+					}
+				} catch {
+					tui.fatal('Invalid embeddings: must be a JSON array of numbers');
+				}
+
+				documents = [
+					{
+						key: args.key,
+						embeddings,
+						metadata,
+					},
+				];
+			}
+		}
+
+		if (documents.length === 0) {
+			tui.fatal('No documents to upsert');
+		}
+
+		const started = Date.now();
+
+		logger.debug(`Upserting ${documents.length} vector(s) to ${args.namespace}`);
+
+		const results = await storage.upsert(args.namespace, ...documents);
+		const durationMs = Date.now() - started;
+
+		if (!options.json) {
+			tui.success(
+				`Upserted ${results.length} vector(s) to ${tui.bold(args.namespace)} (${durationMs}ms)`
+			);
+
+			if (results.length <= 10) {
+				for (const result of results) {
+					tui.arrow(`${result.key} → ${result.id}`);
+				}
+			}
+		}
+
+		return {
+			success: true,
+			namespace: args.namespace,
+			count: results.length,
+			results,
+			durationMs,
+		};
+	},
+});
+
+export default upsertSubcommand;

package/src/cmd/dev/file-watcher.ts

@@ -5,8 +5,8 @@
  * Handles both backend (API, agents, lib) and generates restart signals.
  */
 
-import { watch, type FSWatcher, statSync, readdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { watch, type FSWatcher, statSync, readdirSync, lstatSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
 import type { Logger } from '../../types';
 import { createAgentTemplates, createAPITemplates } from './templates';
 
@@ -34,13 +34,29 @@ export function createFileWatcher(options: FileWatcherOptions): FileWatcherManag
 	let paused = false;
 	let buildCooldownTimer: NodeJS.Timeout | null = null;
 
-	// Watch the entire root directory recursively
-	// This is simpler and more reliable than watching individual paths
-	const watchDirs = [rootDir];
+	// Directories to ignore - these are NEVER traversed into
+	// This prevents EMFILE errors from symlink cycles in node_modules
+	const ignoreDirs = new Set([
+		'.agentuity',
+		'.agents',
+		'.claude',
+		'.code',
+		'.opencode',
+		'node_modules',
+		'.git',
+		'dist',
+		'build',
+		'.next',
+		'.turbo',
+	]);
 
-	// Directories to ignore
+	// Paths to ignore for file change events (but may still be traversed)
 	const ignorePaths = [
 		'.agentuity',
+		'.agents',
+		'.claude',
+		'.code',
+		'.opencode',
 		'node_modules',
 		'.git',
 		'dist',
@@ -168,47 +184,100 @@ export function createFileWatcher(options: FileWatcherOptions): FileWatcherManag
 	}
 
 	/**
-	 * Start watching files
+	 * Recursively collect all directories to watch, skipping ignored directories.
+	 * This prevents EMFILE errors from symlink cycles in node_modules.
 	 */
-	function start() {
-		logger.debug('Starting file watchers for hot reload...');
+	function collectWatchDirs(dir: string, visited: Set<string> = new Set()): string[] {
+		const dirs: string[] = [dir];
 
-		// Watch root directory (already absolute path)
-		for (const watchPath of watchDirs) {
-			try {
-				logger.trace('Setting up watcher for: %s', watchPath);
+		try {
+			// Use lstat to check for symlinks - get the real path to detect cycles
+			const stat = lstatSync(dir);
 
-				const watcher = watch(watchPath, { recursive: true }, (eventType, changedFile) => {
-					handleFileChange(eventType, changedFile, watchPath);
-				});
+			// Skip symlinks to prevent following circular symlinks
+			if (stat.isSymbolicLink()) {
+				logger.trace('Skipping symlink: %s', dir);
+				return [];
+			}
 
-				watchers.push(watcher);
-				logger.trace('Watcher started for: %s', watchPath);
-			} catch (error) {
-				logger.warn('Failed to start watcher for %s: %s', watchPath, error);
+			// Track visited inodes to detect cycles
+			const key = `${stat.dev}:${stat.ino}`;
+			if (visited.has(key)) {
+				logger.trace('Skipping already visited directory (cycle detected): %s', dir);
+				return [];
+			}
+			visited.add(key);
+
+			const entries = readdirSync(dir, { withFileTypes: true });
+
+			for (const entry of entries) {
+				if (!entry.isDirectory()) continue;
+
+				const name = entry.name;
+
+				// Skip ignored directories entirely - this is the key fix
+				if (ignoreDirs.has(name)) {
+					logger.trace('Skipping ignored directory: %s', resolve(dir, name));
+					continue;
+				}
+
+				// Skip hidden directories (except specific ones like .env folders)
+				if (name.startsWith('.')) {
+					logger.trace('Skipping hidden directory: %s', resolve(dir, name));
+					continue;
+				}
+
+				const fullPath = resolve(dir, name);
+				dirs.push(...collectWatchDirs(fullPath, visited));
 			}
+		} catch (error) {
+			logger.trace('Error reading directory %s: %s', dir, error);
 		}
 
-		// Watch additional paths if provided
+		return dirs;
+	}
+
+	/**
+	 * Start watching files
+	 */
+	function start() {
+		logger.debug('Starting file watchers for hot reload...');
+
+		// Collect all directories to watch, excluding node_modules and other ignored dirs
+		const allDirs = collectWatchDirs(rootDir);
+
+		// Add additional paths
 		if (additionalPaths && additionalPaths.length > 0) {
 			for (const additionalPath of additionalPaths) {
 				const fullPath = resolve(rootDir, additionalPath);
-				try {
-					logger.trace('Setting up watcher for additional path: %s', fullPath);
+				allDirs.push(...collectWatchDirs(fullPath));
+			}
+		}
 
-					const watcher = watch(fullPath, { recursive: true }, (eventType, changedFile) => {
-						handleFileChange(eventType, changedFile, fullPath);
-					});
+		// De-duplicate directories
+		const uniqueDirs = [...new Set(allDirs)];
 
-					watchers.push(watcher);
-					logger.trace('Watcher started for additional path: %s', fullPath);
-				} catch (error) {
-					logger.warn('Failed to start watcher for %s: %s', fullPath, error);
-				}
+		logger.debug('Collected %d directories to watch', uniqueDirs.length);
+
+		// Watch each directory non-recursively
+		for (const watchPath of uniqueDirs) {
+			try {
+				// Use non-recursive watch to avoid traversing into node_modules
+				const watcher = watch(watchPath, { recursive: false }, (eventType, changedFile) => {
+					// Construct relative path from rootDir for consistent handling
+					const relPath = changedFile
+						? relative(rootDir, resolve(watchPath, changedFile))
+						: relative(rootDir, watchPath);
+					handleFileChange(eventType, relPath || changedFile, rootDir);
+				});
+
+				watchers.push(watcher);
+			} catch (error) {
+				logger.trace('Failed to start watcher for %s: %s', watchPath, error);
 			}
 		}
 
-		logger.debug('File watchers started (%d paths)', watchers.length);
+		logger.debug('File watchers started (%d directories)', watchers.length);
 	}
 
 	/**