@fadhilp/stateql 0.2.0 → 0.2.2

package/dist/src/cli.js

@@ -36,7 +36,7 @@ const parsed = parseArgs({
 const [command, subcommand, ...rest] = parsed.positionals;
 const values = parsed.values;
 if (values.version) {
-    console.log("0.1.2");
+    console.log(packageVersion());
     process.exit(0);
 }
 if (values.help || !command) {
@@ -502,7 +502,7 @@ function extractHandle(data) {
     return undefined;
 }
 function helpText() {
-    return `StateQL 0.1.2
+    return `StateQL ${packageVersion()}
 
 Usage: stql <command> [arguments] [options]
 
@@ -523,3 +523,7 @@ Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
 Output: --output agent|json|jsonl|text|silent (default: agent).
 Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
 }
+function packageVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+    return packageJson.version;
+}

package/dist/src/index.d.ts

@@ -1,3 +1,3 @@
 export { StateQL } from "./stateql.js";
 export { StateQLError, exitCodeFor } from "./errors.js";
-export type { BatchCommand, BatchCommandName, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, Failure, FilterOptions, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, SqlParameters, StateQLOptions, Success, } from "./types.js";
+export type { BatchCommand, BatchCommandName, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, Failure, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, SqlParameters, StateQLOptions, StateQLSnapshot, Success, } from "./types.js";

package/dist/src/stateql.d.ts

@@ -1,4 +1,4 @@
-import type { BatchCommand, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, FilterOptions, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, StateQLOptions } from "./types.js";
+import type { BatchCommand, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, StateQLOptions, StateQLSnapshot } from "./types.js";
 export declare class StateQL {
     private readonly store;
     private readonly sessionName;
@@ -19,6 +19,9 @@ export declare class StateQL {
     showProfile(name: string): Promise<Response<unknown>>;
     removeProfile(name: string): Promise<Response<unknown>>;
     disconnect(): Promise<Response<unknown>>;
+    snapshot(options?: {
+        historyLimit?: number;
+    }): StateQLSnapshot;
     status(): Promise<Response<unknown>>;
     startSession(name: string): Promise<Response<unknown>>;
     listSessions(): Promise<Response<unknown>>;
@@ -42,7 +45,9 @@ export declare class StateQL {
     inspect(kind: string, table?: string, options?: ExecutionOptions): Promise<Response<unknown>>;
     plan(sql: string, options?: PlanOptions): Promise<Response<unknown>>;
     apply(planId: string, options?: ExecutionOptions): Promise<Response<unknown>>;
-    history(limit?: number): Promise<Response<unknown>>;
+    history(limit?: number): Promise<Response<{
+        history: HistoryEntry[];
+    }>>;
     capabilities(): Promise<Response<unknown>>;
     executeCommand(command: BatchCommand): Promise<Response<unknown>>;
     batch(commands: Iterable<BatchCommand> | AsyncIterable<BatchCommand>, options?: BatchOptions): AsyncGenerator<Response<unknown>>;

package/dist/src/stateql.js

@@ -9,6 +9,8 @@ import { operationData, paginationWarnings, profileData, rowsToCsv, sessionData,
 import { analyzeSql } from "./sql.js";
 import { StateStore, } from "./store.js";
 import { compactRows, defaultHome, hash, parseJson, redact, } from "./util.js";
+const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
+const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
 export class StateQL {
     store;
     sessionName;
@@ -208,6 +210,58 @@ export class StateQL {
             return { data: { disconnected: true }, executed: true };
         });
     }
+    snapshot(options = {}) {
+        const session = this.store
+            .listSessions()
+            .find((candidate) => candidate.name === this.sessionName);
+        if (!session) {
+            throw new StateQLError("INVALID_COMMAND", "The active session was not found.");
+        }
+        const connection = this.store.activeConnection(session);
+        const transaction = session.active_transaction_id
+            ? this.store.getTransaction(session.active_transaction_id)
+            : undefined;
+        const historyLimit = positiveInteger(options.historyLimit ?? DEFAULT_SNAPSHOT_HISTORY_LIMIT, "historyLimit");
+        if (historyLimit > MAX_SNAPSHOT_HISTORY_LIMIT) {
+            throw new StateQLError("INVALID_COMMAND", `historyLimit cannot exceed ${MAX_SNAPSHOT_HISTORY_LIMIT}.`);
+        }
+        return {
+            session: {
+                session_id: session.id,
+                name: session.name,
+                status: session.status,
+            },
+            connection: connection
+                ? {
+                    connection_id: connection.id,
+                    name: connection.name,
+                    status: "connected",
+                    driver: connection.driver,
+                    database: connection.database_name,
+                    read_only: Boolean(connection.read_only),
+                }
+                : null,
+            transaction: transaction
+                ? { transaction_id: transaction.id, state: transaction.state }
+                : null,
+            state_version: connection ? version(connection) : null,
+            state_confidence: connection ? confidence(connection) : null,
+            recent_results: this.store.knownResults(session.id, 10).map((result) => ({
+                alias: result.alias,
+                handle: result.id,
+                rows: result.row_count,
+            })),
+            recent_operations: this.store
+                .recentOperations(session.id, 10)
+                .map((operation) => ({
+                handle: operation.id,
+                type: operation.statement_type,
+                affected_rows: operation.affected_rows,
+                status: operation.status,
+            })),
+            history: this.store.history(session.id, historyLimit).map(historyEntry),
+        };
+    }
     async status() {
         return this.run("status", async (session) => {
             const connection = this.store.activeConnection(session);
@@ -857,17 +911,7 @@ export class StateQL {
             data: {
                 history: this.store
                     .history(session.id, positiveInteger(limit, "limit"))
-                    .map((item) => ({
-                    command_id: item.id,
-                    timestamp: item.timestamp,
-                    session_id: item.session_id,
-                    command: item.command,
-                    handle: item.handle,
-                    executed: Boolean(item.executed),
-                    cached: Boolean(item.cached),
-                    success: Boolean(item.success),
-                    error_code: item.error_code,
-                })),
+                    .map(historyEntry),
             },
         }));
     }
@@ -1328,6 +1372,19 @@ export class StateQL {
         }
     }
 }
+function historyEntry(item) {
+    return {
+        command_id: item.id,
+        timestamp: item.timestamp,
+        session_id: item.session_id,
+        command: item.command,
+        handle: item.handle,
+        executed: Boolean(item.executed),
+        cached: Boolean(item.cached),
+        success: Boolean(item.success),
+        error_code: item.error_code,
+    };
+}
 function markTransactionOutcomeUnknown(store, transactionId, sessionId) {
     try {
         store.markTransactionOutcomeUnknown(transactionId, sessionId);

package/dist/src/types.d.ts

@@ -33,6 +33,50 @@ export interface Failure {
     meta: ResponseMeta;
 }
 export type Response<T> = Success<T> | Failure;
+export interface HistoryEntry {
+    command_id: string;
+    timestamp: string;
+    session_id: string;
+    command: string;
+    handle: string | null;
+    executed: boolean;
+    cached: boolean;
+    success: boolean;
+    error_code: string | null;
+}
+export interface StateQLSnapshot {
+    session: {
+        session_id: string;
+        name: string;
+        status: string;
+    };
+    connection: {
+        connection_id: string;
+        name: string;
+        status: "connected";
+        driver: Driver;
+        database: string;
+        read_only: boolean;
+    } | null;
+    transaction: {
+        transaction_id: string;
+        state: string;
+    } | null;
+    state_version: string | null;
+    state_confidence: StateConfidence | null;
+    recent_results: Array<{
+        alias: string | null;
+        handle: string;
+        rows: number;
+    }>;
+    recent_operations: Array<{
+        handle: string;
+        type: string;
+        affected_rows: number | null;
+        status: string;
+    }>;
+    history: HistoryEntry[];
+}
 export type SqlParameters = unknown[] | Record<string, unknown>;
 export interface ExecutionOptions {
     timeoutMs?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",