@agentuity/cli 0.0.48 → 0.0.50

package/src/cmd/kv/list-namespaces.ts

@@ -0,0 +1,43 @@
+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 keyvalue namespaces',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, project: true },
+	examples: [
+		`${getCommand('kv list-namespaces')} - List all namespaces`,
+		`${getCommand('kv namespaces')} - List namespaces (using alias)`,
+		`${getCommand('kv ns')} - List namespaces (short alias)`,
+	],
+	schema: {
+		response: NamespaceListResponseSchema,
+	},
+	idempotent: true,
+
+	async handler(ctx) {
+		const storage = await createStorageAdapter(ctx);
+		const namespaces = await storage.getNamespaces();
+
+		if (namespaces.length === 0) {
+			tui.info('No namespaces found');
+			return [];
+		}
+
+		tui.info(`Found ${namespaces.length} namespace(s):`);
+		for (const name of namespaces) {
+			tui.arrow(name);
+		}
+
+		return namespaces;
+	},
+});
+
+export default listNamespacesSubcommand;

package/src/cmd/kv/repl.ts

@@ -0,0 +1,284 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import { createRepl, type ReplCommand } from '../../repl';
+import { showBanner } from '../../banner';
+import * as tui from '../../tui';
+import { isPossiblyJSON, tryParseJSON } from '../../json';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+export const replSubcommand = createCommand({
+	name: 'repl',
+	description: 'Start an interactive repl for working with keyvalue database',
+	tags: ['slow', 'requires-auth'],
+	idempotent: false,
+	requires: { auth: true, project: true },
+	examples: [`${getCommand('kv repl')} - Start interactive KV session`],
+
+	async handler(ctx) {
+		showBanner(undefined, true);
+		tui.info('Managing keyvalue store for project');
+		tui.newline();
+		console.log(tui.bold('Org:'.padEnd(10, ' ')), ' ', tui.muted(ctx.project.orgId));
+		console.log(tui.bold('Project:'.padEnd(10, ' ')), ' ', tui.muted(ctx.project.projectId));
+		tui.newline();
+
+		const storage = await createStorageAdapter(ctx);
+
+		const commands: ReplCommand[] = [
+			{
+				name: 'set',
+				aliases: ['put'],
+				description: 'Set a value for a namespace',
+				schema: {
+					args: z.tuple([
+						z.string().min(1),
+						z.string().min(1),
+						z.string().min(1),
+						z.coerce.number().min(60).optional(),
+					]),
+					argNames: ['namespace', 'key', 'value', 'ttl'],
+				},
+				handler: async (ctx) => {
+					ctx.setProgress('saving');
+					const started = Date.now();
+					const contentType = isPossiblyJSON(ctx.parsed.args[2]!)
+						? 'application/json'
+						: 'text/plain';
+					const ttl = ctx.parsed.args.length > 3 ? parseInt(ctx.parsed.args[3]!) : undefined;
+					await storage.set(ctx.parsed.args[0]!, ctx.parsed.args[1]!, ctx.parsed.args[2]!, {
+						contentType,
+						ttl,
+					});
+					ctx.success(`saved in ${(Date.now() - started).toFixed(1)}ms (${contentType})`);
+				},
+			},
+			{
+				name: 'get',
+				description: 'Get a value for a namespace and key',
+				schema: {
+					args: z.tuple([z.string().min(1), z.string().min(1)]),
+					argNames: ['namespace', 'key'],
+				},
+				handler: async (ctx) => {
+					ctx.setProgress('fetching');
+					const started = Date.now();
+					const res = await storage.get(ctx.parsed.args[0]!, ctx.parsed.args[1]!);
+					if (res.exists) {
+						if (res.data) {
+							if (res.contentType?.includes('json')) {
+								const val = tryParseJSON(res.data as unknown as string);
+								ctx.json(val);
+							} else if (res.contentType?.includes('text')) {
+								ctx.write(String(res.data));
+							} else {
+								const b = res.data as ArrayBuffer;
+								ctx.info(`Read ${b.byteLength} bytes (${res.contentType})`);
+							}
+							ctx.success(
+								`retrieved in ${(Date.now() - started).toFixed(1)}ms (${res.contentType})`
+							);
+						} else {
+							ctx.warning(
+								`${ctx.parsed.args[1]!} returned empty data for ${ctx.parsed.args[0]!}`
+							);
+						}
+					} else {
+						ctx.warning(`${ctx.parsed.args[1]!} does not exist in ${ctx.parsed.args[0]!}`);
+					}
+				},
+			},
+			{
+				name: 'delete',
+				aliases: ['rm', 'remove', 'del'],
+				description: 'Delete a value for a namespace and key',
+				schema: {
+					args: z.tuple([z.string().min(1), z.string().min(1)]),
+					argNames: ['namespace', 'key'],
+				},
+				handler: async (ctx) => {
+					ctx.setProgress('deleting');
+					const started = Date.now();
+					await storage.delete(ctx.parsed.args[0]!, ctx.parsed.args[1]!);
+					ctx.success(`deleted in ${(Date.now() - started).toFixed(1)}ms`);
+				},
+			},
+			{
+				name: 'stats',
+				description: 'Get statistics for a namespace or all namespaces',
+				schema: {
+					args: z.tuple([z.string().min(1).optional()]),
+					argNames: ['namespace'],
+				},
+				handler: async (ctx) => {
+					ctx.setProgress('fetching stats');
+					const started = Date.now();
+					if (ctx.parsed.args.length > 0 && ctx.parsed.args[0]) {
+						const stats = await storage.getStats(ctx.parsed.args[0]!);
+						ctx.info(`Statistics for ${tui.bold(ctx.parsed.args[0]!)}:`);
+						ctx.write(`  Keys: ${stats.count}`);
+						const sizeMB = (stats.sum / (1024 * 1024)).toFixed(2);
+						ctx.write(`  Total size: ${sizeMB} MB`);
+						if (stats.createdAt) {
+							ctx.write(`  Created: ${new Date(stats.createdAt).toLocaleString()}`);
+						}
+						if (stats.lastUsedAt) {
+							ctx.write(`  Last used: ${new Date(stats.lastUsedAt).toLocaleString()}`);
+						}
+					} else {
+						const allStats = await storage.getAllStats();
+						const entries = Object.entries(allStats);
+						if (entries.length === 0) {
+							ctx.info('No namespaces found');
+						} else {
+							ctx.info(`Found ${entries.length} namespace(s):`);
+							for (const [name, stats] of entries) {
+								const sizeMB = (stats.sum / (1024 * 1024)).toFixed(2);
+								ctx.write(`  ${tui.bold(name)}: ${stats.count} keys, ${sizeMB} MB`);
+							}
+						}
+					}
+					ctx.success(`retrieved in ${(Date.now() - started).toFixed(1)}ms`);
+				},
+			},
+			{
+				name: 'search',
+				description: 'Search for keys matching a keyword',
+				schema: {
+					args: z.tuple([z.string().min(1), z.string().min(1)]),
+					argNames: ['namespace', 'keyword'],
+				},
+				handler: async (ctx) => {
+					ctx.setProgress('searching');
+					const started = Date.now();
+					const results = await storage.search(ctx.parsed.args[0]!, ctx.parsed.args[1]!);
+					const keys = Object.keys(results);
+					if (keys.length === 0) {
+						ctx.info(
+							`No keys found matching ${tui.bold(ctx.parsed.args[1]!)} in ${tui.bold(ctx.parsed.args[0]!)}`
+						);
+					} else {
+						ctx.info(
+							`Found ${keys.length} key(s) matching ${tui.bold(ctx.parsed.args[1]!)}:`
+						);
+						for (const key of keys) {
+							const item = results[key];
+							if (!item) continue;
+							const sizeMB = (item.size / (1024 * 1024)).toFixed(2);
+							const date = new Date(item.updated_at).toLocaleString();
+							ctx.write(
+								`  ${tui.bold(key)}: ${sizeMB} MB, ${item.contentType}, updated ${date}`
+							);
+						}
+					}
+					ctx.success(`retrieved in ${(Date.now() - started).toFixed(1)}ms`);
+				},
+			},
+			{
+				name: 'keys',
+				aliases: ['ls', 'list'],
+				description: 'List all keys in a namespace',
+				schema: {
+					args: z.tuple([z.string().min(1)]),
+					argNames: ['namespace'],
+				},
+				handler: async (ctx) => {
+					ctx.setProgress('listing keys');
+					const started = Date.now();
+					const keys = await storage.getKeys(ctx.parsed.args[0]!);
+					if (keys.length === 0) {
+						ctx.info(`No keys found in namespace ${tui.bold(ctx.parsed.args[0]!)}`);
+					} else {
+						ctx.info(`Found ${keys.length} key(s) in ${tui.bold(ctx.parsed.args[0]!)}:`);
+						for (const key of keys) {
+							ctx.write(`  ${key}`);
+						}
+					}
+					ctx.success(`retrieved in ${(Date.now() - started).toFixed(1)}ms`);
+				},
+			},
+			{
+				name: 'namespaces',
+				aliases: ['ns', 'list-namespaces'],
+				description: 'List all namespaces',
+				handler: async (ctx) => {
+					ctx.setProgress('listing namespaces');
+					const started = Date.now();
+					const namespaces = await storage.getNamespaces();
+					if (namespaces.length === 0) {
+						ctx.info('No namespaces found');
+					} else {
+						ctx.info(`Found ${namespaces.length} namespace(s):`);
+						for (const name of namespaces) {
+							ctx.write(`  ${name}`);
+						}
+					}
+					ctx.success(`retrieved in ${(Date.now() - started).toFixed(1)}ms`);
+				},
+			},
+			{
+				name: 'create-namespace',
+				aliases: ['create', 'mkns'],
+				description: 'Create a new namespace',
+				schema: {
+					args: z.tuple([z.string().min(1)]),
+					argNames: ['namespace'],
+				},
+				handler: async (ctx) => {
+					ctx.setProgress('creating namespace');
+					const started = Date.now();
+					await storage.createNamespace(ctx.parsed.args[0]!);
+					ctx.success(`created in ${(Date.now() - started).toFixed(1)}ms`);
+				},
+			},
+			{
+				name: 'delete-namespace',
+				aliases: ['rmns', 'delns'],
+				description: 'Delete a namespace and all its keys',
+				schema: {
+					args: z.tuple([z.string().min(1)]),
+					argNames: ['namespace'],
+				},
+				handler: async (ctx) => {
+					ctx.warning(
+						`This will delete namespace ${tui.bold(ctx.parsed.args[0]!)} and ALL its keys.`
+					);
+					const confirm = await new Promise<boolean>((resolve) => {
+						process.stdout.write('Are you sure? (yes/no): ');
+						process.stdin.once('data', (data) => {
+							const answer = data.toString().trim().toLowerCase();
+							resolve(answer === 'yes' || answer === 'y');
+						});
+					});
+					if (!confirm) {
+						ctx.info('Cancelled');
+						return;
+					}
+					ctx.setProgress('deleting namespace');
+					const started = Date.now();
+					await storage.deleteNamespace(ctx.parsed.args[0]!);
+					ctx.success(`deleted in ${(Date.now() - started).toFixed(1)}ms`);
+				},
+			},
+			{
+				name: 'exit',
+				aliases: ['quit'],
+				description: 'Exit the repl',
+				handler: async (ctx) => {
+					return ctx.exit();
+				},
+			},
+		];
+
+		// Start the REPL
+		await createRepl({
+			name: 'keyvalue',
+			prompt: '> ',
+			welcome: tui.muted('Type "help" or / for available commands.'),
+			exitMessage: 'Goodbye!',
+			commands,
+		});
+	},
+});
+
+export default replSubcommand;

package/src/cmd/kv/search.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import * as tui from '../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+const KVSearchResponseSchema = z.object({
+	namespace: z.string().describe('Namespace name'),
+	keyword: z.string().describe('Search keyword used'),
+	results: z.array(
+		z.object({
+			key: z.string().describe('Key name'),
+			size: z.number().describe('Size in bytes'),
+			contentType: z.string().describe('Content type'),
+			updatedAt: z.string().describe('Last updated timestamp'),
+		})
+	),
+});
+
+export const searchSubcommand = createCommand({
+	name: 'search',
+	description: 'Search for keys matching a keyword in a keyvalue namespace',
+	tags: ['read-only', 'slow', 'requires-auth'],
+	requires: { auth: true, project: true },
+	idempotent: true,
+	examples: [
+		`${getCommand('kv search production user')} - Find all user-related keys`,
+		`${getCommand('kv search cache session')} - Find all session keys in cache`,
+		`${getCommand('kv search staging config')} - Find all config keys`,
+	],
+	schema: {
+		args: z.object({
+			name: z.string().min(1).describe('the namespace name'),
+			keyword: z.string().min(1).describe('keyword to use for filtering'),
+		}),
+		response: KVSearchResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const kv = await createStorageAdapter(ctx);
+
+		const results = await kv.search(args.name, args.keyword);
+		const keys = Object.keys(results);
+
+		if (keys.length === 0) {
+			tui.info(`No keys found matching ${tui.bold(args.keyword)} in ${tui.bold(args.name)}`);
+			return {
+				namespace: args.name,
+				keyword: args.keyword,
+				results: [],
+			};
+		}
+
+		tui.info(`Found ${keys.length} key(s) matching ${tui.bold(args.keyword)}:`);
+		for (const key of keys) {
+			const item = results[key];
+			if (!item) continue;
+			const sizeMB = (item.size / (1024 * 1024)).toFixed(2);
+			const date = new Date(item.updated_at).toLocaleString();
+			tui.info(`  ${tui.bold(key)}: ${sizeMB} MB, ${item.contentType}, updated ${date}`);
+		}
+
+		return {
+			namespace: args.name,
+			keyword: args.keyword,
+			results: keys.map((key) => {
+				const item = results[key]!;
+				return {
+					key,
+					size: item.size,
+					contentType: item.contentType,
+					updatedAt: item.updated_at,
+				};
+			}),
+		};
+	},
+});
+
+export default searchSubcommand;

package/src/cmd/kv/set.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import * as tui from '../../tui';
+import { isPossiblyJSON } from '../../json';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+const KVSetResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	namespace: z.string().describe('Namespace name'),
+	key: z.string().describe('Key name'),
+	contentType: z.string().describe('Content type (application/json or text/plain)'),
+	durationMs: z.number().describe('Operation duration in milliseconds'),
+	ttl: z.number().optional().describe('TTL in seconds if set'),
+});
+
+export const setSubcommand = createCommand({
+	name: 'set',
+	aliases: ['put'],
+	description: 'Set a key and value in the keyvalue storage',
+	tags: ['mutating', 'updates-resource', 'slow', 'requires-auth'],
+	idempotent: true,
+	requires: { auth: true, project: true },
+	examples: [
+		`${getCommand('kv set production user:123 \'{"name":"Alice","email":"alice@example.com"}\'')} - Store user data`,
+		`${getCommand('kv set cache session:abc "session-data-here" --ttl 3600')} - Store session with 1h TTL`,
+		`${getCommand('kv set staging cache:homepage "<!DOCTYPE html>..." --ttl 600')} - Cache homepage for 10m`,
+	],
+	schema: {
+		args: z.object({
+			namespace: z.string().min(1).max(64).describe('the namespace name'),
+			key: z.string().min(1).max(64).describe('the key name'),
+			value: z.string().min(1).describe('the value'),
+			ttl: z.coerce.number().min(60).optional().describe('the optional expiration in seconds'),
+		}),
+		response: KVSetResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const started = Date.now();
+		const storage = await createStorageAdapter(ctx);
+		const contentType = isPossiblyJSON(args.value) ? 'application/json' : 'text/plain';
+		const ttl = args.ttl;
+		await storage.set(args.namespace, args.key, args.value, {
+			contentType,
+			ttl,
+		});
+		const durationMs = Date.now() - started;
+		tui.success(`saved in ${durationMs.toFixed(1)}ms (${contentType})`);
+
+		return {
+			success: true,
+			namespace: args.namespace,
+			key: args.key,
+			contentType,
+			durationMs,
+			ttl,
+		};
+	},
+});
+
+export default setSubcommand;

package/src/cmd/kv/stats.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import * as tui from '../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+const KVStatsResponseSchema = z.union([
+	z.object({
+		namespace: z.string().describe('Namespace name'),
+		count: z.number().describe('Number of keys'),
+		sum: z.number().describe('Total size in bytes'),
+		createdAt: z.string().optional().describe('Creation timestamp'),
+		lastUsedAt: z.string().optional().describe('Last used timestamp'),
+	}),
+	z.record(
+		z.string(),
+		z.object({
+			count: z.number().describe('Number of keys'),
+			sum: z.number().describe('Total size in bytes'),
+			createdAt: z.string().optional().describe('Creation timestamp'),
+			lastUsedAt: z.string().optional().describe('Last used timestamp'),
+		})
+	),
+]);
+
+export const statsSubcommand = createCommand({
+	name: 'stats',
+	description: 'Get statistics for keyvalue storage',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, project: true },
+	idempotent: true,
+	examples: [
+		`${getCommand('kv stats')} - Show stats for all namespaces`,
+		`${getCommand('kv stats production')} - Show stats for production namespace`,
+		`${getCommand('kv stats cache')} - Show stats for cache namespace`,
+	],
+	schema: {
+		args: z.object({
+			name: z.string().optional().describe('the keyvalue namespace'),
+		}),
+		response: KVStatsResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const kv = await createStorageAdapter(ctx);
+
+		if (args.name) {
+			const stats = await kv.getStats(args.name);
+			tui.info(`Statistics for ${tui.bold(args.name)}:`);
+			tui.info(`  Keys: ${stats.count}`);
+			const sizeDisplay =
+				stats.sum < 1024 * 1024
+					? `${stats.sum.toLocaleString()} bytes`
+					: `${(stats.sum / (1024 * 1024)).toFixed(2)} MB`;
+			tui.info(`  Total size: ${sizeDisplay} (raw: ${stats.sum})`);
+			if (stats.createdAt) {
+				tui.info(`  Created: ${new Date(stats.createdAt).toLocaleString()}`);
+			}
+			if (stats.lastUsedAt) {
+				tui.info(`  Last used: ${new Date(stats.lastUsedAt).toLocaleString()}`);
+			}
+
+			return {
+				namespace: args.name,
+				count: stats.count,
+				sum: stats.sum,
+				createdAt: stats.createdAt,
+				lastUsedAt: stats.lastUsedAt,
+			};
+		} else {
+			const allStats = await kv.getAllStats();
+			const entries = Object.entries(allStats);
+
+			if (entries.length === 0) {
+				tui.info('No namespaces found');
+				return {};
+			}
+
+			tui.info(
+				`Found ${entries.length} ${tui.plural(entries.length, 'namespace', 'namespaces')}:`
+			);
+			for (const [name, stats] of entries) {
+				const sizeDisplay =
+					stats.sum < 1024 * 1024
+						? `${stats.sum.toLocaleString()} bytes`
+						: `${(stats.sum / (1024 * 1024)).toFixed(2)} MB`;
+				tui.arrow(`${tui.bold(name.padEnd(15, ' '))}: ${stats.count} keys, ${sizeDisplay}`);
+			}
+
+			return allStats;
+		}
+	},
+});
+
+export default statsSubcommand;

package/src/cmd/kv/util.ts

@@ -0,0 +1,32 @@
+import { KeyValueStorageService, Logger } from '@agentuity/core';
+import { createServerFetchAdapter } from '@agentuity/server';
+import { loadProjectSDKKey } from '../../config';
+import { ErrorCode } from '../../errors';
+import type { Config } from '../../types';
+import * as tui from '../../tui';
+
+export async function createStorageAdapter(ctx: {
+	logger: Logger;
+	projectDir: string;
+	config: Config | null;
+}) {
+	const sdkKey = await loadProjectSDKKey(ctx.projectDir);
+	if (!sdkKey) {
+		tui.fatal(
+			`Couldn't find the AGENTUITY_SDK_KEY in ${ctx.projectDir} .env file`,
+			ErrorCode.CONFIG_NOT_FOUND
+		);
+	}
+
+	const adapter = createServerFetchAdapter(
+		{
+			headers: {
+				Authorization: `Bearer ${sdkKey}`,
+			},
+		},
+		ctx.logger
+	);
+
+	const baseUrl = ctx.config?.overrides?.catalyst_url ?? 'https://catalyst.agentuity.cloud';
+	return new KeyValueStorageService(baseUrl, adapter);
+}

package/src/cmd/objectstore/delete-bucket.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import * as tui from '../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+export const deleteBucketSubcommand = createCommand({
+	name: 'delete-bucket',
+	description: 'Delete an object storage bucket and all its contents',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
+	idempotent: true,
+	requires: { auth: true, project: true },
+	examples: [
+		`${getCommand('objectstore delete-bucket temp')} - Delete temp bucket (interactive)`,
+		`${getCommand('objectstore delete-bucket old-uploads --confirm')} - Force delete without confirmation`,
+	],
+	schema: {
+		args: z.object({
+			bucket: z.string().min(1).max(64).describe('the name of the bucket'),
+			confirm: z
+				.boolean()
+				.optional()
+				.default(false)
+				.describe('if true will not prompt for confirmation'),
+		}),
+		response: z.object({
+			success: z.boolean().describe('Whether the deletion succeeded'),
+			bucket: z.string().describe('Deleted bucket name'),
+			message: z.string().optional().describe('Confirmation message'),
+		}),
+	},
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const objectStore = await createStorageAdapter(ctx);
+
+		if (!args.confirm) {
+			if (!process.stdin.isTTY) {
+				tui.fatal('No TTY and --confirm is not set. Refusing to delete');
+			}
+			tui.warning(`This will delete bucket ${tui.bold(args.bucket)} and ALL its contents.`);
+			const confirm = await new Promise<boolean>((resolve) => {
+				process.stdout.write('Are you sure? (yes/no): ');
+				process.stdin.once('data', (data) => {
+					const answer = data.toString().trim().toLowerCase();
+					resolve(answer === 'yes' || answer === 'y');
+				});
+			});
+
+			if (!confirm) {
+				tui.info('Cancelled');
+				return { success: false, bucket: args.bucket, message: 'Cancelled' };
+			}
+		}
+
+		const deleted = await objectStore.deleteBucket(args.bucket);
+
+		if (deleted) {
+			tui.success(`Bucket ${tui.bold(args.bucket)} deleted`);
+		} else {
+			tui.error(`Bucket ${tui.bold(args.bucket)} not found`);
+		}
+
+		return {
+			success: deleted,
+			bucket: args.bucket,
+			message: deleted ? `Bucket ${args.bucket} deleted` : `Bucket ${args.bucket} not found`,
+		};
+	},
+});
+
+export default deleteBucketSubcommand;