@carllee1983/dbcli 7.0.0 → 8.0.0

package/dist/cli.mjs

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "7.0.0",
+  version: "8.0.0",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {
@@ -70,6 +70,7 @@ var package_default = {
     build: "bun run scripts/build.ts",
     "build:determinism": "bun run scripts/check-build-determinism.ts",
     prepublishOnly: "bun run build",
+    audit: "bun run scripts/audit.ts",
     "release:check": "bash scripts/release-check.sh",
     "plugin:sync": "bun run scripts/sync-plugin-assets.ts --write",
     "plugin:check": "bun run scripts/sync-plugin-assets.ts",
@@ -88,6 +89,7 @@ var package_default = {
     "agent-core:check": "bun run scripts/check-agent-core-purity.ts",
     "core-stdout:check": "bun run scripts/check-core-no-stdout.ts",
     "plan:check": "bun run scripts/check-plan-acceptance.ts",
+    "forgeflow:check": "bun run scripts/check-forgeflow-adoption.ts && bun run scripts/check-forgeflow-handoff.ts",
     typecheck: "tsc --noEmit --pretty false",
     "typecheck:tests": "tsc --noEmit --pretty false -p tsconfig.tests.json",
     "test:perf": "bun test ./tests/perf/*.bench.ts",
@@ -103,7 +105,7 @@ var package_default = {
     "lru-cache": "^11.4.0",
     "lucide-react": "^1.16.0",
     mongodb: "^7.2.0",
-    mysql2: "^3.22.3",
+    mysql2: "^3.24.3",
     "node-sql-parser": "5",
     open: "^11.0.0",
     pg: "^8.21.0",
@@ -125,7 +127,7 @@ var package_default = {
     "@types/react-dom": "^19.2.3",
     autoprefixer: "^10.5.0",
     "dts-bundle-generator": "^9.5.1",
-    eslint: "^10.4.0",
+    eslint: "^10.9.1",
     "happy-dom": "^20.10.6",
     postcss: "^8.5.26",
     prettier: "^3.8.3",
@@ -134,6 +136,7 @@ var package_default = {
     "typescript-eslint": "^8.59.4"
   },
   overrides: {
+    "@humanfs/node": "^0.16.8",
     "brace-expansion": "^5.0.9",
     browserslist: "^4.28.7",
     postcss: "^8.5.26",
@@ -146,7 +149,7 @@ function isStandaloneVersionRequest(args) {
   return args.length === 1 && (args[0] === "--version" || args[0] === "-V");
 }
 var program;
-if (import.meta.main && isStandaloneVersionRequest(process.argv.slice(2))) {
+if (import.meta.main && !process.argv.slice(2).includes("--agent-output") && isStandaloneVersionRequest(process.argv.slice(2))) {
   console.log(package_default.version);
 } else {
   const runtimePath = "./cli-runtime";

package/dist/core.d.ts

@@ -8,6 +8,7 @@ import { z } from 'zod';
  */
 export type DatabaseSystem = "postgresql" | "mysql" | "mariadb" | "mongodb" | "redis" | "elasticsearch";
 type SqlDatabaseSystem = Extract<DatabaseSystem, "postgresql" | "mysql" | "mariadb">;
+type SqlExecutionMode = "normal" | "native-read-only";
 type QueryableDatabaseSystem = Exclude<DatabaseSystem, SqlDatabaseSystem>;
 /**
  * Connection configuration for database adapters
@@ -129,7 +130,7 @@ export interface TableSchema {
 	/** Type of table (table or view) */
 	tableType?: "table" | "view";
 }
-type ConnectionErrorCode = "ECONNREFUSED" | "ETIMEDOUT" | "AUTH_FAILED" | "ENOTFOUND" | "EHOSTUNREACH" | "CONNECTION_LOST" | "TOO_MANY_CONNECTIONS" | "TLS_ERROR" | "SERVER_NOT_READY" | "CONNECTION_REJECTED" | "SQL_SYNTAX_ERROR" | "STATEMENT_TIMEOUT" | "TABLE_NOT_FOUND" | "COLUMN_NOT_FOUND" | "UNKNOWN";
+type ConnectionErrorCode = "ECONNREFUSED" | "ETIMEDOUT" | "AUTH_FAILED" | "ENOTFOUND" | "EHOSTUNREACH" | "CONNECTION_LOST" | "TOO_MANY_CONNECTIONS" | "TLS_ERROR" | "SERVER_NOT_READY" | "CONNECTION_REJECTED" | "SQL_SYNTAX_ERROR" | "STATEMENT_TIMEOUT" | "TABLE_NOT_FOUND" | "COLUMN_NOT_FOUND" | "QUERY_ONLY_BOUNDARY_FAILED" | "UNKNOWN";
 export declare class ConnectionError extends Error {
 	/** Error category code */
 	code: ConnectionErrorCode;
@@ -141,6 +142,8 @@ export declare class ConnectionError extends Error {
 	 * it to tell an agent what `--statement-timeout <ms>` it was already up against.
 	 */
 	limitMs?: number | undefined;
+	/** Whether an interactive caller may safely retry the statement after reconnecting. */
+	readonly retrySafe: boolean;
 	constructor(
 	/** Error category code */
 	code: ConnectionErrorCode, 
@@ -153,7 +156,9 @@ export declare class ConnectionError extends Error {
 	 * consumers can state it without parsing `message`; the recovery envelope needs
 	 * it to tell an agent what `--statement-timeout <ms>` it was already up against.
 	 */
-	limitMs?: number | undefined);
+	limitMs?: number | undefined, 
+	/** Whether an interactive caller may safely retry the statement after reconnecting. */
+	retrySafe?: boolean);
 }
 /**
  * Result of a database query or command execution
@@ -224,6 +229,7 @@ export interface DatabaseAdapter {
 	 */
 	execute<T>(sql: string, params?: (string | number | boolean | null)[], options?: {
 		noLimit?: boolean;
+		sqlMode?: SqlExecutionMode;
 	}): Promise<ExecutionResult<T>>;
 	/**
 	 * List all tables in the connected database
@@ -255,6 +261,7 @@ export interface DatabaseAdapter {
 	 */
 	getServerVersion(): Promise<string>;
 }
+type SideEffectTier = "readonly" | "dry-run" | "local-write" | "db-write" | "interactive" | "none";
 interface BlacklistConfig {
 	/** Table names to block all operations on */
 	tables: string[];
@@ -3281,6 +3288,294 @@ export declare function isGlobalConfigPath(path: string): boolean;
 export declare function getProjectStoragePath(projectPath: string): string;
 export declare function resolveConfigStoragePath(path: string): Promise<string>;
 export declare function writeProjectBinding(projectPath: string, storagePath?: string): Promise<ProjectConfigBinding>;
+export declare const CAPABILITY_CONTRACT_SCHEMA_VERSION: 1;
+/**
+ * Risk vocabulary, reused verbatim from the Agent Task Pack contract
+ * (`AgentTaskRisk`) so a pack's step risk and a capability's risk are the same
+ * four words. `sideEffect` carries the finer existing `SideEffectTier` beside
+ * it, because collapsing `local-write` and `db-write` into `write` would hide
+ * the one distinction a caller most needs.
+ */
+export type CapabilityRisk = "readonly" | "dry-run" | "write" | "unknown";
+export interface Capability {
+	/** Stable dotted id, e.g. `schema.read`. The value external Skills pin. */
+	readonly id: string;
+	readonly description: string;
+	/** Space-separated live CLI command path, e.g. `audit tail`. */
+	readonly command: string;
+	readonly risk: CapabilityRisk;
+	/** The precise pre-existing side-effect tier this risk was derived from. */
+	readonly sideEffect: SideEffectTier;
+	/** Engines on which the capability is supported or limited, sorted. */
+	readonly engines: readonly DatabaseSystem[];
+	/**
+	 * The subset of `engines` the matrix marks `limited` rather than `supported`.
+	 *
+	 * Carried separately because folding it into `engines` would discard
+	 * information the matrix already holds: `data.delete` works on Redis, but not
+	 * the way it works on PostgreSQL, and a caller choosing an engine deserves to
+	 * know which before it commits.
+	 */
+	readonly limitedEngines: readonly DatabaseSystem[];
+	/** True when the capability works irrespective of the configured engine. */
+	readonly engineIndependent: boolean;
+	readonly minimumPermission: Permission;
+	readonly requiresConnection: boolean;
+	/**
+	 * True when the capability changes connection identity, permission or
+	 * credentials — the class of change `DBCLI_AGENT_MODE=1` refuses outright.
+	 */
+	readonly mutatesConfiguration: boolean;
+	readonly supportsJson: boolean;
+	readonly supportsEvidence: boolean;
+}
+export interface CapabilityCatalog {
+	readonly schemaVersion: typeof CAPABILITY_CONTRACT_SCHEMA_VERSION;
+	readonly capabilities: readonly Capability[];
+}
+export type CapabilityCheckStatus = "available" | "unavailable" | "unknown";
+/**
+ * Why a capability is not available. `null` only ever accompanies `available`.
+ *
+ * `context-unavailable` is distinct from `engine`/`permission` on purpose: with
+ * no local config there is nothing to evaluate against, and reporting that as
+ * an engine mismatch would invent a fact. It is still not `available` — absence
+ * of context never reads as permission to act.
+ *
+ * `context-unresolvable` is a *different* fact from `context-unavailable`, and
+ * conflating them was a real defect: a config whose `{"$env": "..."}` password
+ * reference points at an unset variable is present and perfectly readable, and
+ * reporting "no configuration was readable" there states something false. This
+ * command needs no credential, but the one config reader resolves them before
+ * it will answer, so the honest report is "a config exists and could not be
+ * turned into an evaluable context" — never "there is no config".
+ *
+ * `agent-mode` is an environment gate, not an execution-time one. Under
+ * `DBCLI_AGENT_MODE=1` every configuration, permission and credential change is
+ * refused unconditionally, and that is fully knowable without connecting. The
+ * "available is not approval" disclaimer does not cover it: blacklist and human
+ * consent are decided at execution time, whereas this is decided here, and the
+ * contract's primary consumer is exactly the agent the flag describes.
+ */
+export type CapabilityUnavailableReason = "unknown-capability" | "context-unavailable" | "context-unresolvable" | "engine" | "agent-mode" | "permission";
+export interface CapabilityCheckContext {
+	readonly engine: DatabaseSystem;
+	readonly permission: Permission;
+	/** Named v2 connection in effect, or null for a v1/single-connection config. */
+	readonly connectionName: string | null;
+	/** `DBCLI_AGENT_MODE=1`: configuration changes are refused unconditionally. */
+	readonly agentMode: boolean;
+}
+/**
+ * Why there is no context, when there is none.
+ *
+ * `absent` means nothing is configured here. `unresolvable` means something is,
+ * and it could not be turned into an engine and a permission. Only the first
+ * justifies telling a caller there is no configuration.
+ */
+export type CapabilityContextFailure = "absent" | "unresolvable";
+export interface CapabilityCheckResultEntry {
+	readonly id: string;
+	readonly status: CapabilityCheckStatus;
+	readonly reason: CapabilityUnavailableReason | null;
+}
+export interface CapabilityCheckReport {
+	readonly schemaVersion: typeof CAPABILITY_CONTRACT_SCHEMA_VERSION;
+	readonly ok: boolean;
+	/** The de-duplicated requirement list, in first-seen order. */
+	readonly required: readonly string[];
+	readonly context: CapabilityCheckContext | null;
+	readonly results: readonly CapabilityCheckResultEntry[];
+	readonly warnings: readonly string[];
+}
+/**
+ * Every capability, sorted by id.
+ *
+ * Sorting is the whole determinism guarantee: two builds of the same version
+ * emit byte-identical catalogs regardless of declaration order, so a consumer
+ * can diff two outputs and see only real changes.
+ */
+export declare const CAPABILITIES: readonly Capability[];
+export declare function findCapability(id: string): Capability | undefined;
+export declare function listCapabilityIds(): readonly string[];
+/** The catalog as an external consumer receives it. */
+export declare function buildCapabilityCatalog(): {
+	schemaVersion: typeof CAPABILITY_CONTRACT_SCHEMA_VERSION;
+	capabilities: readonly Capability[];
+};
+export declare class CapabilityRequirementError extends Error {
+	constructor(message: string);
+}
+interface ParsedRequirements {
+	readonly ids: readonly string[];
+	readonly warnings: readonly string[];
+}
+/**
+ * Parse `--require a,b,a` into an ordered, unique id list.
+ *
+ * A repeated id is de-duplicated rather than refused, and the duplication is
+ * reported as a warning. Refusing would punish the common case of two Skills
+ * concatenating their requirement lists, and answering the same id twice would
+ * make `results` a multiset that a consumer has to fold itself. Neither
+ * behaviour is guessable, so it is stated here and in the spec.
+ *
+ * Empty input, or any empty element, is refused: a requirement list that
+ * accidentally evaluated to "nothing required" would report `ok: true` and read
+ * as a green light.
+ */
+export declare function parseRequirements(raw: string): ParsedRequirements;
+export declare function checkCapabilities(required: readonly string[], context: CapabilityCheckContext | null, warnings?: readonly string[], contextFailure?: CapabilityContextFailure): CapabilityCheckReport;
+export declare class CapabilityContractError extends Error {
+	constructor(message: string);
+}
+export declare function parseCapabilityCatalog(value: unknown): CapabilityCatalog;
+export declare function parseCapabilityCheckReport(value: unknown): CapabilityCheckReport;
+type GuideRisk = "readonly" | "dry-run" | "write" | "unknown";
+interface GuideStep {
+	/** 1-based ordinal in the emitted plan. */
+	order: number;
+	/** Exact dbcli command the agent should run next, e.g. `dbcli q @diag/long-running --format json`. */
+	command: string;
+	/** One-sentence justification for this step. */
+	rationale: string;
+	/** Forward-compatible risk tag; v1.14.0 always emits `readonly`. */
+	risk: GuideRisk;
+	/** Short description of expected output shape (helps agents know when to bail). */
+	expects: string;
+	/** Snippet key when the step came from a saved query (e.g. `@diag/long-running`). */
+	snippet?: string;
+	/** Snippet `intent` taxonomy slot when applicable. */
+	intent?: string;
+	/** v1.17.0+: step requires interactive TTY (e.g. `dbcli init`). `dbcli recover --apply` skips these. */
+	interactive?: boolean;
+	/** v1.17.0+: true when the step mutates the connected database. Gates `--apply --allow-write=write-cmd`. */
+	dbWrite?: boolean;
+	/** v1.17.0+: placeholder tokens that must be resolved before `--apply` can execute this step (e.g. `['<table>']`). */
+	placeholders?: string[];
+	/** Set only on steps inside `branches[id].steps`. Agents may ignore. */
+	branchId?: string;
+}
+declare const RECOVERY_SCHEMA_VERSION: 1;
+declare const RECOVERY_CODES: readonly [
+	"CONFIG_MISSING",
+	"CONN_REFUSED",
+	"CONN_AUTH_FAILED",
+	"CONN_TIMEOUT",
+	"CONN_HOST_NOT_FOUND",
+	"CONN_UNKNOWN",
+	"PERMISSION_DENIED",
+	"BLACKLIST_TABLE",
+	"BLACKLIST_COLUMN_WRITE",
+	"SNIPPET_NOT_FOUND",
+	"SNIPPET_AMBIGUOUS",
+	"SNIPPET_PARAM_MISSING",
+	"SCHEMA_CACHE_MISSING",
+	"UNKNOWN"
+];
+type RecoveryCode = (typeof RECOVERY_CODES)[number];
+type RecoveryCategory = "config" | "connection" | "permission" | "blacklist" | "snippet" | "schema-cache" | "unknown";
+interface RecoveryError {
+	/** Stable code from RECOVERY_CODES. */
+	code: RecoveryCode;
+	category: RecoveryCategory;
+	/** User-safe message; never includes hostnames, ports, or secrets. */
+	message: string;
+	/**
+	 * Bounded set of structured details for agents. Allowed keys are intentionally
+	 * limited so the envelope shape stays predictable across versions.
+	 */
+	details?: {
+		table?: string;
+		columns?: string;
+		requiredPermission?: string;
+		connectionCode?: ConnectionErrorCode;
+		snippet?: string;
+		intent?: string;
+		paramName?: string;
+	};
+}
+type BranchId = string;
+interface BranchPlan {
+	/** Human-readable summary; agents can show this to the user. */
+	description: string;
+	/** Steps inside the branch. `order` is 1-based WITHIN the branch. */
+	steps: GuideStep[];
+}
+interface BranchFork {
+	/** 1-based step order in `recovery` after which a fork may happen. v1: always 1. */
+	after: number;
+	/** Enumeration of possible branchIds; must equal Object.keys(branches). */
+	branchIds: BranchId[];
+}
+interface RecoveryEnvelope {
+	schemaVersion: typeof RECOVERY_SCHEMA_VERSION;
+	/** ISO-8601 UTC timestamp at envelope construction. */
+	generatedAt: string;
+	/** Always `false` — the envelope is only emitted on failure. Reserved for future success-shape symmetry. */
+	ok: false;
+	error: RecoveryError;
+	/** Ordered, deterministic recovery plan. Capped by `MAX_RECOVERY_STEPS` (6). */
+	recovery: GuideStep[];
+	/** v1.17.0 P4: optional read-only probe appended by classifyError; runs only after `--apply` succeeds. */
+	verify?: GuideStep;
+	/** Optional branch plans keyed by BranchId. Present iff `branchFork` is present. */
+	branches?: Record<BranchId, BranchPlan>;
+	/** Optional fork descriptor. Present iff `branches` is present. */
+	branchFork?: BranchFork;
+}
+export declare const OPERATION_ENVELOPE_SCHEMA_VERSION: 1;
+export type OperationEnvelopeOperation = "capabilities.check" | "capabilities.list";
+export type OperationEnvelopeStatus = "succeeded" | "failed";
+export type OperationEnvelopeEvidenceKind = "receipt" | "audit" | "verification-artifact";
+export interface OperationEnvelopeContext {
+	readonly engine: DatabaseSystem;
+	readonly permission: Permission;
+	readonly connectionName: string | null;
+	readonly agentMode: boolean;
+	readonly correlationId?: string;
+}
+export interface OperationEnvelopeCapabilityResult {
+	readonly id: string;
+	readonly status: "available" | "unavailable" | "unknown";
+	readonly reason: "unknown-capability" | "context-unavailable" | "context-unresolvable" | "engine" | "agent-mode" | "permission" | null;
+}
+export interface OperationEnvelopeCapabilitiesCheckData {
+	readonly required: readonly string[];
+	readonly results: readonly OperationEnvelopeCapabilityResult[];
+}
+export interface OperationEnvelopeWarning {
+	readonly code: string;
+	readonly message: string;
+}
+export interface OperationEnvelopeEvidenceReference {
+	readonly kind: OperationEnvelopeEvidenceKind;
+	readonly id: string;
+	readonly digest?: string;
+}
+export interface OperationEnvelopeError {
+	readonly code: string;
+	readonly message: string;
+}
+export interface OperationEnvelope {
+	readonly schemaVersion: typeof OPERATION_ENVELOPE_SCHEMA_VERSION;
+	readonly ok: boolean;
+	readonly operation: OperationEnvelopeOperation;
+	readonly status: OperationEnvelopeStatus;
+	readonly context: OperationEnvelopeContext | null;
+	readonly data: OperationEnvelopeCapabilitiesCheckData | CapabilityCatalog | null;
+	readonly warnings: readonly OperationEnvelopeWarning[];
+	readonly evidence: readonly OperationEnvelopeEvidenceReference[];
+	readonly recovery: RecoveryEnvelope | null;
+	readonly error: OperationEnvelopeError | null;
+}
+export type OperationEnvelopeParseResult = {
+	readonly ok: true;
+	readonly value: OperationEnvelope;
+} | {
+	readonly ok: false;
+	readonly reason: string;
+};
+export declare function parseOperationEnvelope(input: unknown): OperationEnvelopeParseResult;
 /**
  * Read and fully resolve a `.dbcli` project config: handles project-binding
  * indirection, v1/v2 formats, per-connection `.env` loading and `{$env}`