@agentuity/cli 2.0.12 → 2.0.13

package/src/cmd/coder/workspace/create.ts

@@ -10,29 +10,14 @@ import * as tui from '../../../tui';
 import { getCommand } from '../../../command-prefix';
 import { ErrorCode } from '../../../errors';
 import { resolveGitHubRepo } from '../resolve-repo';
-
-const EMPTY_WORKSPACE_ERROR =
-	'A workspace needs at least one repo, saved skill, skill bucket, or agent';
-
-function hasWorkspaceSelections(input: CoderCreateWorkspaceRequest): boolean {
-	return (
-		(input.repos?.length ?? 0) > 0 ||
-		(input.savedSkillIds?.length ?? 0) > 0 ||
-		(input.skillBucketIds?.length ?? 0) > 0 ||
-		(input.enabledAgents?.length ?? 0) > 0
-	);
-}
-
-function formatWorkspaceValidationMessage(issues: Array<{ message: string }>): string {
-	const messages = [...new Set(issues.map((issue) => issue.message).filter(Boolean))];
-	if (messages.length === 0) {
-		return 'Invalid workspace configuration';
-	}
-	if (messages.includes(EMPTY_WORKSPACE_ERROR)) {
-		return `${EMPTY_WORKSPACE_ERROR}. Use --repo or --enabled-agents.`;
-	}
-	return messages.join('; ');
-}
+import {
+	EMPTY_WORKSPACE_ERROR,
+	formatWorkspaceValidationMessage,
+	hasWorkspaceSelections,
+	parseCommaList,
+	printWorkspaceSummary,
+	readSetupScript,
+} from './common';
 
 export const createWorkspaceSubcommand = createSubcommand({
 	name: 'create',
@@ -49,9 +34,9 @@ export const createWorkspaceSubcommand = createSubcommand({
 		},
 		{
 			command: getCommand(
-				'coder workspace create "My Workspace" --enabled-agents code-review --description "For frontend work" --scope org'
+				'coder workspace create "My Workspace" --dependency git --setup-script-file ./setup.sh --scope org'
 			),
-			description: 'Create an org-scoped workspace with description and agents',
+			description: 'Create an org-scoped workspace with dependencies and a setup script',
 		},
 		{
 			command: getCommand('coder workspace create "My Workspace" --enabled-agents code-review'),
@@ -74,6 +59,18 @@ export const createWorkspaceSubcommand = createSubcommand({
 			scope: z.string().optional().describe('Workspace scope: user or org'),
 			repo: z.string().optional().describe('Repository URL to add'),
 			repoBranch: z.string().optional().describe('Branch for the repository'),
+			dependency: z
+				.string()
+				.optional()
+				.describe('Comma-separated APT dependencies to install into workspace snapshots'),
+			setupScript: z
+				.string()
+				.optional()
+				.describe('Inline shell script to run while preparing workspace snapshots'),
+			setupScriptFile: z
+				.string()
+				.optional()
+				.describe('Path to a shell script to run while preparing workspace snapshots'),
 			enabledAgents: z
 				.string()
 				.optional()
@@ -105,15 +102,26 @@ export const createWorkspaceSubcommand = createSubcommand({
 				return;
 			}
 		}
+		if (opts?.dependency) {
+			body.dependencies = parseCommaList(opts.dependency);
+		}
+		try {
+			const setupScript = await readSetupScript({
+				setupScript: opts?.setupScript,
+				setupScriptFile: opts?.setupScriptFile,
+			});
+			if (setupScript !== undefined) body.setupScript = setupScript;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			tui.fatal(`Failed to read setup script: ${msg}`, ErrorCode.VALIDATION_FAILED);
+			return;
+		}
 		if (opts?.enabledAgents) {
-			body.enabledAgents = opts.enabledAgents
-				.split(',')
-				.map((name) => name.trim())
-				.filter(Boolean);
+			body.enabledAgents = parseCommaList(opts.enabledAgents);
 		}
 		if (!hasWorkspaceSelections(body)) {
 			tui.fatal(
-				`Failed to create workspace: ${EMPTY_WORKSPACE_ERROR}. Use --repo or --enabled-agents.`,
+				`Failed to create workspace: ${EMPTY_WORKSPACE_ERROR}. Use --repo, --dependency, --setup-script, or --enabled-agents.`,
 				ErrorCode.VALIDATION_FAILED
 			);
 		}
@@ -132,9 +140,6 @@ export const createWorkspaceSubcommand = createSubcommand({
 
 		try {
 			const created = await client.createWorkspace(validationResult.data);
-			const createdEnabledAgents = Array.isArray(created.enabledAgents)
-				? created.enabledAgents.filter((name): name is string => typeof name === 'string')
-				: [];
 
 			if (options.json) {
 				return created;
@@ -142,16 +147,7 @@ export const createWorkspaceSubcommand = createSubcommand({
 
 			tui.success(`Workspace ${created.id} created.`);
 			tui.newline();
-			tui.output(`  Name:        ${tui.bold(created.name)}`);
-			if (created.description) {
-				tui.output(`  Description: ${created.description}`);
-			}
-			tui.output(`  Scope:       ${created.scope}`);
-			tui.output(`  Repos:       ${created.repoCount}`);
-			tui.output(`  Selections:  ${created.selectionCount}`);
-			if (createdEnabledAgents.length > 0) {
-				tui.output(`  Agents:      ${createdEnabledAgents.join(', ')}`);
-			}
+			printWorkspaceSummary(created);
 
 			return created;
 		} catch (err) {

package/src/cmd/coder/workspace/get.ts

@@ -5,6 +5,7 @@ import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getCommand } from '../../../command-prefix';
 import { ErrorCode } from '../../../errors';
+import { printWorkspaceSummary } from './common';
 
 function formatRelativeTime(isoDate: string): string {
 	const parsed = new Date(isoDate).getTime();
@@ -63,11 +64,7 @@ export const getWorkspaceSubcommand = createSubcommand({
 			tui.header(`Workspace: ${workspace.name}`);
 			tui.newline();
 			tui.output(`  ID:          ${workspace.id}`);
-			tui.output(`  Name:        ${tui.bold(workspace.name)}`);
-			if (workspace.description) {
-				tui.output(`  Description: ${workspace.description}`);
-			}
-			tui.output(`  Scope:       ${workspace.scope}`);
+			printWorkspaceSummary(workspace);
 			tui.output(`  Owner:       ${workspace.ownerUserId}`);
 			tui.output(`  Created:     ${formatRelativeTime(workspace.createdAt)}`);
 			tui.output(`  Updated:     ${formatRelativeTime(workspace.updatedAt)}`);

package/src/cmd/coder/workspace/index.ts

@@ -2,6 +2,9 @@ import { createCommand } from '../../../types';
 import { listSubcommand } from './list';
 import { createWorkspaceSubcommand } from './create';
 import { getWorkspaceSubcommand } from './get';
+import { refreshWorkspaceSnapshotSubcommand } from './refresh';
+import { updateWorkspaceSubcommand } from './update';
+import { validateWorkspaceDependenciesSubcommand } from './validate-dependencies';
 import { deleteWorkspaceSubcommand } from './delete';
 import { getCommand } from '../../../command-prefix';
 
@@ -30,11 +33,18 @@ export const workspaceCommand = createCommand({
 			command: getCommand('coder workspace delete ws_abc123'),
 			description: 'Delete a workspace',
 		},
+		{
+			command: getCommand('coder workspace validate-dependencies git,nodejs'),
+			description: 'Validate workspace dependencies',
+		},
 	],
 	subcommands: [
 		listSubcommand,
 		createWorkspaceSubcommand,
 		getWorkspaceSubcommand,
+		updateWorkspaceSubcommand,
+		refreshWorkspaceSnapshotSubcommand,
+		validateWorkspaceDependenciesSubcommand,
 		deleteWorkspaceSubcommand,
 	],
 });

package/src/cmd/coder/workspace/list.ts

@@ -83,6 +83,8 @@ export const listSubcommand = createSubcommand({
 				Name: w.name,
 				Scope: w.scope,
 				Repos: String(w.repoCount),
+				Deps: String(w.dependencies?.length ?? 0),
+				Snapshot: w.snapshot?.status ?? '',
 				Selections: String(w.selectionCount),
 				Created: formatRelativeTime(w.createdAt),
 			})),
@@ -91,6 +93,8 @@ export const listSubcommand = createSubcommand({
 				{ name: 'Name', alignment: 'left' },
 				{ name: 'Scope', alignment: 'center' },
 				{ name: 'Repos', alignment: 'right' },
+				{ name: 'Deps', alignment: 'right' },
+				{ name: 'Snapshot', alignment: 'left' },
 				{ name: 'Selections', alignment: 'right' },
 				{ name: 'Created', alignment: 'right' },
 			]

package/src/cmd/coder/workspace/refresh.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { APIError, ValidationOutputError } from '@agentuity/core';
+import { CoderClient } from '@agentuity/core/coder';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+import { printWorkspaceSummary } from './common';
+
+export const refreshWorkspaceSnapshotSubcommand = createSubcommand({
+	name: 'refresh',
+	aliases: ['snapshot-refresh', 'rebuild'],
+	description: 'Refresh a Coder workspace snapshot',
+	tags: ['mutating', 'requires-auth'],
+	requires: { auth: true, org: true },
+	examples: [
+		{
+			command: getCommand('coder workspace refresh ws_abc123'),
+			description: 'Queue a workspace snapshot refresh',
+		},
+	],
+	schema: {
+		args: z.object({
+			workspaceId: z.string().describe('Workspace ID to refresh'),
+		}),
+		options: z.object({
+			url: z.string().optional().describe('Coder API URL override'),
+		}),
+	},
+	async handler(ctx) {
+		const { args, opts, options } = ctx;
+		const client = new CoderClient({
+			apiKey: ctx.auth.apiKey,
+			url: opts?.url,
+			orgId: ctx.orgId,
+		});
+
+		try {
+			const workspace = await client.refreshWorkspaceSnapshot(args.workspaceId);
+			if (options.json) {
+				return workspace;
+			}
+
+			tui.success(`Workspace ${workspace.id} snapshot refresh queued.`);
+			tui.newline();
+			printWorkspaceSummary(workspace);
+			return workspace;
+		} catch (err) {
+			if (err instanceof ValidationOutputError) {
+				ctx.logger.trace('Validation response URL: %s', err.url ?? 'unknown');
+				ctx.logger.trace('Validation issues: %s', JSON.stringify(err.issues, null, 2));
+			}
+			if (err instanceof APIError && err.status >= 400 && err.status < 500) {
+				tui.fatal(
+					`Failed to refresh workspace snapshot: ${err.message}`,
+					ErrorCode.VALIDATION_FAILED
+				);
+			}
+			const msg = err instanceof Error ? err.message : String(err);
+			tui.fatal(`Failed to refresh workspace snapshot: ${msg}`, ErrorCode.NETWORK_ERROR);
+		}
+	},
+});

package/src/cmd/coder/workspace/update.ts

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import { APIError, ValidationInputError, ValidationOutputError } from '@agentuity/core';
+import {
+	CoderClient,
+	CoderUpdateWorkspaceRequestSchema,
+	type CoderUpdateWorkspaceRequest,
+} from '@agentuity/core/coder';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+import { resolveGitHubRepo } from '../resolve-repo';
+import {
+	formatWorkspaceValidationMessage,
+	hasWorkspaceUpdate,
+	parseCommaList,
+	printWorkspaceSummary,
+	readSetupScript,
+} from './common';
+
+export const updateWorkspaceSubcommand = createSubcommand({
+	name: 'update',
+	aliases: ['edit', 'patch'],
+	description: 'Update a Coder workspace',
+	tags: ['mutating', 'requires-auth'],
+	requires: { auth: true, org: true },
+	examples: [
+		{
+			command: getCommand('coder workspace update ws_abc123 --dependency git,nodejs'),
+			description: 'Update workspace dependencies',
+		},
+		{
+			command: getCommand('coder workspace update ws_abc123 --setup-script-file ./setup.sh'),
+			description: 'Update the workspace setup script',
+		},
+	],
+	schema: {
+		args: z.object({
+			workspaceId: z.string().describe('Workspace ID to update'),
+		}),
+		options: z.object({
+			url: z.string().optional().describe('Coder API URL override'),
+			name: z.string().optional().describe('Workspace name'),
+			description: z.string().optional().describe('Workspace description'),
+			scope: z.string().optional().describe('Workspace scope: user or org'),
+			repo: z.string().optional().describe('Repository URL to set'),
+			repoBranch: z.string().optional().describe('Branch for the repository'),
+			dependency: z
+				.string()
+				.optional()
+				.describe('Comma-separated APT dependencies to install into workspace snapshots'),
+			setupScript: z
+				.string()
+				.optional()
+				.describe('Inline shell script to run while preparing workspace snapshots'),
+			setupScriptFile: z
+				.string()
+				.optional()
+				.describe('Path to a shell script to run while preparing workspace snapshots'),
+			enabledAgents: z
+				.string()
+				.optional()
+				.describe('Comma-separated built-in/custom agents to include'),
+		}),
+	},
+	async handler(ctx) {
+		const { args, opts, options } = ctx;
+		const client = new CoderClient({
+			apiKey: ctx.auth.apiKey,
+			url: opts?.url,
+			orgId: ctx.orgId,
+		});
+
+		const body: CoderUpdateWorkspaceRequest = {
+			...(opts?.name && { name: opts.name }),
+			...(opts?.description && { description: opts.description }),
+			...(opts?.scope && { scope: opts.scope as 'user' | 'org' }),
+		};
+
+		if (opts?.repo) {
+			if (!options.json) tui.output('Resolving repository...');
+			try {
+				const resolved = await resolveGitHubRepo(client, opts.repo, opts?.repoBranch);
+				body.repos = [resolved];
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				tui.fatal(`Failed to resolve repository: ${msg}`, ErrorCode.VALIDATION_FAILED);
+				return;
+			}
+		}
+		if (opts?.dependency) {
+			body.dependencies = parseCommaList(opts.dependency);
+		}
+		try {
+			const setupScript = await readSetupScript({
+				setupScript: opts?.setupScript,
+				setupScriptFile: opts?.setupScriptFile,
+			});
+			if (setupScript !== undefined) body.setupScript = setupScript;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			tui.fatal(`Failed to read setup script: ${msg}`, ErrorCode.VALIDATION_FAILED);
+			return;
+		}
+		if (opts?.enabledAgents) {
+			body.enabledAgents = parseCommaList(opts.enabledAgents);
+		}
+		if (!hasWorkspaceUpdate(body)) {
+			tui.fatal(
+				'Failed to update workspace: At least one field must be provided.',
+				ErrorCode.VALIDATION_FAILED
+			);
+		}
+
+		const validationResult = CoderUpdateWorkspaceRequestSchema.safeParse(body);
+		if (!validationResult.success) {
+			ctx.logger.trace(
+				'Validation issues: %s',
+				JSON.stringify(validationResult.error.issues, null, 2)
+			);
+			tui.fatal(
+				`Failed to update workspace: ${formatWorkspaceValidationMessage(validationResult.error.issues)}`,
+				ErrorCode.VALIDATION_FAILED
+			);
+		}
+
+		try {
+			const updated = await client.updateWorkspace(args.workspaceId, validationResult.data);
+
+			if (options.json) {
+				return updated;
+			}
+
+			tui.success(`Workspace ${updated.id} updated.`);
+			tui.newline();
+			printWorkspaceSummary(updated);
+			return updated;
+		} catch (err) {
+			if (err instanceof ValidationInputError || err instanceof ValidationOutputError) {
+				ctx.logger.trace('Validation response URL: %s', err.url ?? 'unknown');
+				ctx.logger.trace('Validation issues: %s', JSON.stringify(err.issues, null, 2));
+				tui.fatal(
+					`Failed to update workspace: ${formatWorkspaceValidationMessage(err.issues)}`,
+					ErrorCode.VALIDATION_FAILED
+				);
+			}
+			if (err instanceof APIError && err.status >= 400 && err.status < 500) {
+				tui.fatal(`Failed to update workspace: ${err.message}`, ErrorCode.VALIDATION_FAILED);
+			}
+			const msg = err instanceof Error ? err.message : String(err);
+			tui.fatal(`Failed to update workspace: ${msg}`, ErrorCode.NETWORK_ERROR);
+		}
+	},
+});

package/src/cmd/coder/workspace/validate-dependencies.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { APIError, ValidationOutputError } from '@agentuity/core';
+import { CoderClient } from '@agentuity/core/coder';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+import { parseCommaList } from './common';
+
+export const validateWorkspaceDependenciesSubcommand = createSubcommand({
+	name: 'validate-dependencies',
+	aliases: ['validate-deps'],
+	description: 'Validate APT dependencies for Coder workspace snapshots',
+	tags: ['read-only', 'requires-auth'],
+	idempotent: true,
+	requires: { auth: true, org: true },
+	examples: [
+		{
+			command: getCommand('coder workspace validate-dependencies git,nodejs'),
+			description: 'Validate dependency package names',
+		},
+	],
+	schema: {
+		args: z.object({
+			dependencies: z.string().describe('Comma-separated APT dependencies to validate'),
+		}),
+		options: z.object({
+			url: z.string().optional().describe('Coder API URL override'),
+		}),
+	},
+	async handler(ctx) {
+		const { args, opts, options } = ctx;
+		const dependencies = parseCommaList(args.dependencies);
+		if (dependencies.length === 0) {
+			tui.fatal('At least one dependency is required.', ErrorCode.VALIDATION_FAILED);
+		}
+
+		const client = new CoderClient({
+			apiKey: ctx.auth.apiKey,
+			url: opts?.url,
+			orgId: ctx.orgId,
+		});
+
+		try {
+			const result = await client.validateWorkspaceDependencies(dependencies);
+			if (options.json) {
+				return result;
+			}
+
+			if (result.valid.length > 0) {
+				tui.success(`Valid dependencies: ${result.valid.join(', ')}`);
+			}
+			if (result.invalid.length > 0) {
+				tui.error(`Invalid dependencies: ${result.invalid.length}`);
+				for (const invalid of result.invalid) {
+					tui.output(`  - ${invalid.package}: ${invalid.error}`);
+				}
+			}
+			return result;
+		} catch (err) {
+			if (err instanceof ValidationOutputError) {
+				ctx.logger.trace('Validation response URL: %s', err.url ?? 'unknown');
+				ctx.logger.trace('Validation issues: %s', JSON.stringify(err.issues, null, 2));
+			}
+			if (err instanceof APIError && err.status >= 400 && err.status < 500) {
+				tui.fatal(
+					`Failed to validate dependencies: ${err.message}`,
+					ErrorCode.VALIDATION_FAILED
+				);
+			}
+			const msg = err instanceof Error ? err.message : String(err);
+			tui.fatal(`Failed to validate dependencies: ${msg}`, ErrorCode.NETWORK_ERROR);
+		}
+	},
+});

package/src/cmd/project/random-name.ts

@@ -0,0 +1,152 @@
+/**
+ * Generates project-derived suggestions for resource names (DB / S3 bucket).
+ *
+ * The CLI shows these as a dim "press Enter to use ..." default in the create flow.
+ * If the user presses Enter, the suggestion is sent to the server. Otherwise the
+ * server is responsible for assigning a name when none is provided.
+ *
+ * Both suggestions are validated against the same rules the server enforces
+ * (`validateBucketName` / `validateDatabaseName` from `@agentuity/server`) so the
+ * happy path can never produce an invalid suggestion.
+ */
+import { validateBucketName, validateDatabaseName } from '@agentuity/server';
+
+const BUCKET_MAX = 63;
+const BUCKET_MIN = 3;
+const DB_MAX = 63;
+
+/** 3 lowercase alphanumeric chars, e.g. "k7p". */
+function shortSuffix(): string {
+	// toString(36) yields [0-9a-z]; slice 3 chars after the "0." prefix.
+	const s = Math.random().toString(36).slice(2, 5);
+	// Pad in the (extremely unlikely) case the slice is shorter than 3 chars.
+	return s.length === 3 ? s : (s + '000').slice(0, 3);
+}
+
+/**
+ * Sanitize a project name into the bucket-name alphabet:
+ * - lowercase
+ * - spaces / underscores / dots → hyphens
+ * - drop anything else
+ * - collapse and trim hyphens
+ * - strip reserved prefixes (`agentuity*`, `ag-*`, `ago-*`, `xn--`)
+ */
+function sanitizeForBucket(name: string): string {
+	let out = name
+		.toLowerCase()
+		.trim()
+		.replace(/[\s_.]+/g, '-')
+		.replace(/[^a-z0-9-]/g, '')
+		.replace(/-+/g, '-')
+		.replace(/^-+|-+$/g, '');
+
+	// Strip reserved prefixes (rules from validateBucketName).
+	while (
+		out.startsWith('agentuity') ||
+		out.startsWith('ag-') ||
+		out.startsWith('ago-') ||
+		out.startsWith('xn--')
+	) {
+		if (out.startsWith('agentuity')) out = out.slice('agentuity'.length);
+		else if (out.startsWith('ago-')) out = out.slice('ago-'.length);
+		else if (out.startsWith('ag-')) out = out.slice('ag-'.length);
+		else if (out.startsWith('xn--')) out = out.slice('xn--'.length);
+		out = out.replace(/^-+/, '');
+	}
+	return out;
+}
+
+/**
+ * Sanitize a project name into the database-name alphabet:
+ * - lowercase
+ * - non `[a-z0-9_]` → `_`
+ * - collapse and trim underscores
+ * - ensure it starts with a letter or underscore (prepend `p_` otherwise)
+ * - strip reserved `pg_` prefix
+ */
+function sanitizeForDatabase(name: string): string {
+	let out = name
+		.toLowerCase()
+		.trim()
+		.replace(/[^a-z0-9_]+/g, '_')
+		.replace(/_+/g, '_')
+		.replace(/^_+|_+$/g, '');
+
+	if (!/^[a-z_]/.test(out)) {
+		out = out.length > 0 ? `p_${out}` : '';
+	}
+	while (out.startsWith('pg_')) {
+		out = out.slice(3).replace(/^_+/, '');
+		if (!/^[a-z_]/.test(out) && out.length > 0) out = `p_${out}`;
+	}
+	return out;
+}
+
+/**
+ * Truncate so the final string (`<base>-<suffixWithDash>`) fits within `max` chars
+ * while keeping the suffix intact and not ending on a hyphen.
+ */
+function truncateBaseHyphen(base: string, suffixWithDash: string, max: number): string {
+	const room = max - suffixWithDash.length;
+	if (room <= 0) return '';
+	let out = base.slice(0, room);
+	out = out.replace(/-+$/, '');
+	return out;
+}
+
+/** Same as `truncateBaseHyphen` but for underscore-joined names (database). */
+function truncateBaseUnderscore(base: string, suffixWithUnderscore: string, max: number): string {
+	const room = max - suffixWithUnderscore.length;
+	if (room <= 0) return '';
+	let out = base.slice(0, room);
+	out = out.replace(/_+$/, '');
+	return out;
+}
+
+/**
+ * Generate a suggested S3 bucket name derived from the project name.
+ * Format: `<sanitized-project>-storage-<3char>` (≤ 63 chars).
+ *
+ * Falls back to `bucket-<3char><3char>` if the project name produces nothing usable.
+ * Always returns a value that passes `validateBucketName`.
+ */
+export function suggestBucketName(projectName: string): string {
+	const sanitized = sanitizeForBucket(projectName);
+
+	// Try a few times in case sanitization + suffix happens to land on something invalid.
+	for (let attempt = 0; attempt < 5; attempt++) {
+		const suffix = `-storage-${shortSuffix()}`;
+		const base = truncateBaseHyphen(sanitized, suffix, BUCKET_MAX);
+		const candidate = base.length > 0 ? `${base}${suffix}` : `bucket${suffix}`;
+		if (candidate.length >= BUCKET_MIN && validateBucketName(candidate).valid) {
+			return candidate;
+		}
+	}
+
+	// Pure fallback: short, always-valid generic name.
+	const fallback = `bucket-${shortSuffix()}${shortSuffix()}`;
+	return validateBucketName(fallback).valid ? fallback : `bucket-${shortSuffix()}aaa`;
+}
+
+/**
+ * Generate a suggested PostgreSQL database name derived from the project name.
+ * Format: `<sanitized-project>_db_<3char>` (≤ 63 chars).
+ *
+ * Falls back to `db_<3char><3char>` if the project name produces nothing usable.
+ * Always returns a value that passes `validateDatabaseName`.
+ */
+export function suggestDatabaseName(projectName: string): string {
+	const sanitized = sanitizeForDatabase(projectName);
+
+	for (let attempt = 0; attempt < 5; attempt++) {
+		const suffix = `_db_${shortSuffix()}`;
+		const base = truncateBaseUnderscore(sanitized, suffix, DB_MAX);
+		const candidate = base.length > 0 ? `${base}${suffix}` : `db${suffix}`;
+		if (validateDatabaseName(candidate).valid) {
+			return candidate;
+		}
+	}
+
+	const fallback = `db_${shortSuffix()}${shortSuffix()}`;
+	return validateDatabaseName(fallback).valid ? fallback : `db_${shortSuffix()}aaa`;
+}