@carllee1983/dbcli 1.57.0 → 1.58.0

package/dist/cli.mjs

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.57.0",
+  version: "1.58.0",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {
@@ -77,12 +77,14 @@ var package_default = {
     "test:unit": "bun test tests/unit tests/core",
     "test:integration": "bun test tests/integration",
     "test:gherkin": "bun test tests/gherkin",
-    "test:docker": "docker compose -f docker-compose.test.yml up -d --wait && bun test tests/integration/adapters; docker compose -f docker-compose.test.yml down",
+    "test:docker": "docker compose -f docker-compose.test.yml up -d --wait && bun test tests/integration; docker compose -f docker-compose.test.yml down",
+    "services:check": "bun run scripts/check-test-services.ts",
     "docs:check": "bun run scripts/check-user-docs.ts",
     "contract:check": "bun run scripts/check-cli-contract.ts",
     "skill:check": "bun run scripts/check-skill-parity.ts",
     "platform:check": "bun run scripts/check-platform-parity.ts",
     "agent-core:check": "bun run scripts/check-agent-core-purity.ts",
+    "core-stdout:check": "bun run scripts/check-core-no-stdout.ts",
     typecheck: "tsc --noEmit --pretty false",
     "test:perf": "bun test ./tests/perf/*.bench.ts",
     lint: "eslint src tests scripts --ext .ts --max-warnings=0",

package/dist/core.d.ts

@@ -410,8 +410,17 @@ export declare class AdapterFactory {
  * Used to wrap the execution result and metadata of data modification operations
  */
 export interface DataExecutionResult {
-	/** Execution status: success or error */
-	status: "success" | "error";
+	/**
+	 * What became of the operation.
+	 *
+	 * `success` means the statement ran — `rows_affected` may still be 0 if it
+	 * matched nothing. `cancelled` means a user declined at the confirmation.
+	 * `dry_run` means it was previewed and deliberately not run. The last two
+	 * were reported as `success` with `rows_affected: 0` until 2.0.0, which made
+	 * them indistinguishable from a write that matched no rows and caused the
+	 * audit log to record declined operations as writes that happened.
+	 */
+	status: "success" | "error" | "cancelled" | "dry_run";
 	/** Type of operation executed */
 	operation: "insert" | "update" | "delete";
 	/** Number of rows affected */
@@ -434,7 +443,53 @@ export interface DataExecutionOptions {
 	force?: boolean;
 	/** Verbose output */
 	verbose?: boolean;
+	/**
+	 * How to ask the caller's user whether to proceed.
+	 *
+	 * Core states what is about to happen; the caller decides how to present it
+	 * and how to collect an answer. Required whenever a mutation would execute
+	 * without `force`, and absent by design rather than defaulted: silently
+	 * proceeding unconfirmed, or silently declining, are both worse than saying
+	 * that nobody was available to ask.
+	 */
+	confirm?: MutationConfirmer;
+}
+/**
+ * Everything a caller needs to describe a pending mutation to its user.
+ */
+export interface MutationConfirmationRequest {
+	operation: DataExecutionResult["operation"];
+	/**
+	 * Which engine will run it.
+	 *
+	 * Only presentation depends on this: a MongoDB shell line or a Redis command
+	 * announced as "Generated SQL" would be a lie about what is being approved,
+	 * and approving the wrong thing is the failure this whole prompt exists to
+	 * prevent.
+	 */
+	engine: "sql" | "mongodb" | "redis";
+	/** The parameterised statement that will run if confirmed */
+	sql: string;
+	/** Values bound to the statement's placeholders */
+	params: (string | number | boolean | null)[];
+	/**
+	 * Whether this operation is irreversible.
+	 *
+	 * A flag rather than the warning sentence and the question themselves, which
+	 * is what this carried first. The division is not "core cannot translate" —
+	 * `permission-guard` translates the refusal it throws, and so does
+	 * `blacklist-validator` — it is that core owns facts and the command layer
+	 * owns presentation. Whether a delete can be undone is a fact. Which sentence
+	 * a person is shown about it, in what tone, on which stream, is presentation,
+	 * and a caller embedding the executor should be able to say it in its own
+	 * product's voice rather than inheriting dbcli's.
+	 */
+	destructive: boolean;
 }
+/**
+ * Returns true to proceed, false to abandon the mutation.
+ */
+export type MutationConfirmer = (request: MutationConfirmationRequest) => Promise<boolean>;
 interface SqlConnectionConfig {
 	system: "postgresql" | "mysql" | "mariadb";
 	host: string | {
@@ -1355,6 +1410,7 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			max_entries: number;
 		};
 	};
+	permission: "admin" | "query-only" | "read-write" | "data-admin";
 	connection: {
 		password: string | {
 			$env: string;
@@ -1453,7 +1509,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		} | undefined;
 		caPath?: string | undefined;
 	};
-	permission: "admin" | "query-only" | "read-write" | "data-admin";
 	metadata: {
 		version: string;
 		createdAt?: string | undefined;
@@ -1706,8 +1761,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 				$env: string;
 			} | undefined;
 			timeout?: number | undefined;
-			statementTimeout?: number | undefined;
 			permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+			statementTimeout?: number | undefined;
 			envFile?: string | undefined;
 			environment?: string | undefined;
 		}>,
@@ -1868,8 +1923,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			tls?: boolean | undefined;
 			srv?: boolean | undefined;
 			timeout?: number | undefined;
-			statementTimeout?: number | undefined;
 			permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+			statementTimeout?: number | undefined;
 			envFile?: string | undefined;
 			environment?: string | undefined;
 		}>,
@@ -1976,8 +2031,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 				$env: string;
 			} | undefined;
 			timeout?: number | undefined;
-			statementTimeout?: number | undefined;
 			permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+			statementTimeout?: number | undefined;
 			envFile?: string | undefined;
 			environment?: string | undefined;
 		}>,
@@ -2089,8 +2144,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 				$env: string;
 			};
 			rejectUnauthorized: boolean;
-			protocol: "http" | "https";
 			permission: "admin" | "query-only" | "read-write" | "data-admin";
+			protocol: "http" | "https";
 			timeout?: number | undefined;
 			statementTimeout?: number | undefined;
 			nodes?: string[] | undefined;
@@ -2122,6 +2177,7 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			} | undefined;
 			rejectUnauthorized?: boolean | undefined;
 			timeout?: number | undefined;
+			permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 			statementTimeout?: number | undefined;
 			protocol?: "http" | "https" | undefined;
 			nodes?: string[] | undefined;
@@ -2132,7 +2188,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 				$env: string;
 			} | undefined;
 			caPath?: string | undefined;
-			permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 			envFile?: string | undefined;
 			environment?: string | undefined;
 		}>
@@ -2231,8 +2286,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		};
 		rejectUnauthorized: boolean;
-		protocol: "http" | "https";
 		permission: "admin" | "query-only" | "read-write" | "data-admin";
+		protocol: "http" | "https";
 		timeout?: number | undefined;
 		statementTimeout?: number | undefined;
 		nodes?: string[] | undefined;
@@ -2263,8 +2318,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2296,8 +2351,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		tls?: boolean | undefined;
 		srv?: boolean | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2318,8 +2373,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2341,6 +2396,7 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		} | undefined;
 		rejectUnauthorized?: boolean | undefined;
 		timeout?: number | undefined;
+		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		statementTimeout?: number | undefined;
 		protocol?: "http" | "https" | undefined;
 		nodes?: string[] | undefined;
@@ -2351,7 +2407,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		caPath?: string | undefined;
-		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	}>>;
@@ -2546,8 +2601,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		};
 		rejectUnauthorized: boolean;
-		protocol: "http" | "https";
 		permission: "admin" | "query-only" | "read-write" | "data-admin";
+		protocol: "http" | "https";
 		timeout?: number | undefined;
 		statementTimeout?: number | undefined;
 		nodes?: string[] | undefined;
@@ -2589,8 +2644,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2622,8 +2677,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		tls?: boolean | undefined;
 		srv?: boolean | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2644,8 +2699,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2667,6 +2722,7 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		} | undefined;
 		rejectUnauthorized?: boolean | undefined;
 		timeout?: number | undefined;
+		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		statementTimeout?: number | undefined;
 		protocol?: "http" | "https" | undefined;
 		nodes?: string[] | undefined;
@@ -2677,7 +2733,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		caPath?: string | undefined;
-		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	}>;
@@ -2822,8 +2877,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		};
 		rejectUnauthorized: boolean;
-		protocol: "http" | "https";
 		permission: "admin" | "query-only" | "read-write" | "data-admin";
+		protocol: "http" | "https";
 		timeout?: number | undefined;
 		statementTimeout?: number | undefined;
 		nodes?: string[] | undefined;
@@ -2865,8 +2920,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2898,8 +2953,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		tls?: boolean | undefined;
 		srv?: boolean | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2920,8 +2975,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2943,6 +2998,7 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		} | undefined;
 		rejectUnauthorized?: boolean | undefined;
 		timeout?: number | undefined;
+		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		statementTimeout?: number | undefined;
 		protocol?: "http" | "https" | undefined;
 		nodes?: string[] | undefined;
@@ -2953,7 +3009,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		caPath?: string | undefined;
-		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	}>;
@@ -3105,7 +3160,7 @@ export declare class DataExecutor {
 	private getQuoteChar;
 	private checkBlacklist;
 	private executeMutation;
-	private successResult;
+	private outcomeResult;
 	private handleMutationError;
 	/**
 	 * Build a parameterized UPDATE SQL statement