@agentuity/cli 0.0.48 → 0.0.49

package/src/cmd/kv/delete-namespace.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import { ErrorCode } from '../../errors';
+import * as tui from '../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+export const deleteNamespaceSubcommand = createCommand({
+	name: 'delete-namespace',
+	aliases: ['rm-namespace'],
+	description: 'Delete a keyvalue namespace and all its keys',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth', 'requires-project'],
+	idempotent: true,
+	requires: { auth: true, project: true },
+	examples: [
+		`${getCommand('kv delete-namespace staging')} - Delete staging namespace (interactive)`,
+		`${getCommand('kv rm-namespace cache --confirm')} - Delete cache without confirmation`,
+		`${getCommand('kv delete-namespace production --confirm')} - Force delete production`,
+	],
+	schema: {
+		args: z.object({
+			name: z.string().min(1).max(64).describe('the namespace name'),
+			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'),
+			namespace: z.string().describe('Deleted namespace name'),
+			message: z.string().optional().describe('Confirmation message'),
+		}),
+	},
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const kv = await createStorageAdapter(ctx);
+
+		if (!args.confirm) {
+			if (!process.stdin.isTTY) {
+				tui.fatal(
+					'No TTY and --confirm is not set. Refusing to delete',
+					ErrorCode.VALIDATION_FAILED
+				);
+			}
+			tui.warning(`This will delete namespace ${tui.bold(args.name)} 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) {
+				tui.info('Cancelled');
+				return { success: false, namespace: args.name, message: 'Cancelled' };
+			}
+		}
+
+		await kv.deleteNamespace(args.name);
+		tui.success(`Namespace ${tui.bold(args.name)} deleted`);
+
+		return {
+			success: true,
+			namespace: args.name,
+			message: `Namespace ${args.name} deleted`,
+		};
+	},
+});
+
+export default deleteNamespaceSubcommand;

package/src/cmd/kv/delete.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import * as tui from '../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+const KVDeleteResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	namespace: z.string().describe('Namespace name'),
+	key: z.string().describe('Key name'),
+	durationMs: z.number().describe('Operation duration in milliseconds'),
+});
+
+export const deleteSubcommand = createCommand({
+	name: 'delete',
+	aliases: ['del', 'rm', 'remove'],
+	description: 'Delete a key from the keyvalue storage',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
+	idempotent: true,
+	requires: { auth: true, project: true },
+	examples: [
+		`${getCommand('kv delete production user:123')} - Delete user data`,
+		`${getCommand('kv delete cache session:abc')} - Delete cached session`,
+		`${getCommand('kv rm staging cache:homepage')} - Delete homepage cache (using alias)`,
+	],
+	schema: {
+		args: z.object({
+			namespace: z.string().min(1).describe('the namespace name'),
+			key: z.string().min(1).describe('the key name'),
+		}),
+		response: KVDeleteResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const started = Date.now();
+		const storage = await createStorageAdapter(ctx);
+		await storage.delete(args.namespace, args.key);
+		const durationMs = Date.now() - started;
+		tui.success(`deleted in ${durationMs.toFixed(1)}ms`);
+
+		return {
+			success: true,
+			namespace: args.namespace,
+			key: args.key,
+			durationMs,
+		};
+	},
+});
+
+export default deleteSubcommand;

package/src/cmd/kv/get.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import * as tui from '../../tui';
+import { tryParseJSON } from '../../json';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+const KVGetResponseSchema = z.object({
+	exists: z.boolean().describe('Whether the key exists'),
+	data: z.union([z.string(), z.any()]).optional().describe('Value data (string or binary)'),
+	contentType: z.string().optional().describe('Content type'),
+});
+
+export const getSubcommand = createCommand({
+	name: 'get',
+	description: 'Get a value from the keyvalue storage',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, project: true },
+	examples: [
+		`${getCommand('kv get production user:123')} - Get user data`,
+		`${getCommand('kv get cache session:abc')} - Get cached session`,
+		`${getCommand('kv get staging cache:homepage')} - Get homepage cache`,
+	],
+	schema: {
+		args: z.object({
+			namespace: z.string().min(1).describe('the namespace name'),
+			key: z.string().min(1).describe('the key name'),
+		}),
+		response: KVGetResponseSchema,
+	},
+	idempotent: true,
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const storage = await createStorageAdapter(ctx);
+		const started = Date.now();
+		const res = await storage.get(args.namespace, args.key);
+		if (res.exists) {
+			if (res.data) {
+				if (res.contentType?.includes('json')) {
+					const val = tryParseJSON(res.data as unknown as string);
+					tui.json(val);
+				} else if (res.contentType?.includes('text')) {
+					console.log(String(res.data));
+				} else {
+					const b = res.data as ArrayBuffer;
+					tui.info(`Read ${b.byteLength} bytes (${res.contentType})`);
+				}
+				tui.success(`retrieved in ${(Date.now() - started).toFixed(1)}ms (${res.contentType})`);
+			} else {
+				tui.warning(`${args.key} returned empty data for ${args.namespace}`);
+			}
+		} else {
+			tui.warning(`${args.key} does not exist in ${args.namespace}`);
+		}
+
+		return {
+			exists: res.exists,
+			data: res.data,
+			contentType: res.exists ? res.contentType : undefined,
+		};
+	},
+});
+
+export default getSubcommand;

package/src/cmd/kv/index.ts

@@ -0,0 +1,31 @@
+import { createCommand } from '../../types';
+import { createNamespaceSubcommand } from './create-namespace';
+import { deleteSubcommand } from './delete';
+import { deleteNamespaceSubcommand } from './delete-namespace';
+import { getSubcommand } from './get';
+import { keysSubcommand } from './keys';
+import { listNamespacesSubcommand } from './list-namespaces';
+import { replSubcommand } from './repl';
+import { searchSubcommand } from './search';
+import { setSubcommand } from './set';
+import { statsSubcommand } from './stats';
+
+export const command = createCommand({
+	name: 'keyvalue',
+	aliases: ['kv'],
+	description: 'Manage keyvalue storage for your projects',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	subcommands: [
+		replSubcommand,
+		getSubcommand,
+		setSubcommand,
+		deleteSubcommand,
+		statsSubcommand,
+		searchSubcommand,
+		keysSubcommand,
+		listNamespacesSubcommand,
+		createNamespaceSubcommand,
+		deleteNamespaceSubcommand,
+	],
+	requires: { auth: true, project: true },
+});

package/src/cmd/kv/keys.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import * as tui from '../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+const KVKeysResponseSchema = z.object({
+	namespace: z.string().describe('Namespace name'),
+	keys: z.array(z.string()).describe('List of keys in the namespace'),
+});
+
+export const keysSubcommand = createCommand({
+	name: 'keys',
+	aliases: ['ls', 'list'],
+	description: 'List all keys in a keyvalue namespace',
+	tags: ['read-only', 'slow', 'requires-auth'],
+	requires: { auth: true, project: true },
+	idempotent: true,
+	examples: [
+		`${getCommand('kv keys production')} - List all keys in production`,
+		`${getCommand('kv ls cache')} - List all cached keys (using alias)`,
+		`${getCommand('kv list staging')} - List all staging keys`,
+	],
+	schema: {
+		args: z.object({
+			name: z.string().min(1).describe('the namespace name'),
+		}),
+		response: KVKeysResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const kv = await createStorageAdapter(ctx);
+
+		const keys = await kv.getKeys(args.name);
+
+		if (keys.length === 0) {
+			tui.info(`No keys found in namespace ${tui.bold(args.name)}`);
+			return {
+				namespace: args.name,
+				keys: [],
+			};
+		}
+
+		tui.info(`Found ${keys.length} key(s) in ${tui.bold(args.name)}:`);
+		for (const key of keys) {
+			tui.info(`  ${key}`);
+		}
+
+		return {
+			namespace: args.name,
+			keys,
+		};
+	},
+});
+
+export default keysSubcommand;

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;