@feasibleone/blong-gogo 1.30.0 → 1.31.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.31.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.30.0...blong-gogo-v1.31.0) (2026-09-07)
+
+
+### Features
+
+* blong-commander ([#163](https://github.com/feasibleone/blong/issues/163)) ([b7fe11b](https://github.com/feasibleone/blong/commit/b7fe11b44b1d1ee0e14e4be96523d403b59311c2))
+
 ## [1.30.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.29.0...blong-gogo-v1.30.0) (2026-08-21)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.30.0",
+  "version": "1.31.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },

package/src/adapter/server/k8s.ts

@@ -43,6 +43,51 @@ const errorMap: IErrorMap = {
 
 let _errors: Errors<typeof errorMap>;
 
+/**
+ * Commander explorer categories for namespaced resources. Each category groups
+ * the resource types the adapter can list (`{ns}.<resource>.find`). The
+ * category / resource levels are synthetic navigation (no cluster calls).
+ */
+const CATEGORIES: Array<{name: string; label: string; resources: Array<{type: string; label: string}>}> = [
+    {
+        name: 'workloads',
+        label: 'Workloads',
+        resources: [
+            {type: 'deployment', label: 'Deployments'},
+            {type: 'replicaset', label: 'ReplicaSets'},
+            {type: 'daemonset', label: 'DaemonSets'},
+            {type: 'statefulset', label: 'StatefulSets'},
+            {type: 'pod', label: 'Pods'},
+        ],
+    },
+    {
+        name: 'networking',
+        label: 'Networking',
+        resources: [
+            {type: 'service', label: 'Services'},
+            {type: 'ingress', label: 'Ingresses'},
+            {type: 'networkpolicy', label: 'NetworkPolicies'},
+        ],
+    },
+    {
+        name: 'storage',
+        label: 'Storage',
+        resources: [
+            {type: 'persistentvolume', label: 'PersistentVolumes'},
+            {type: 'persistentvolumeclaim', label: 'PersistentVolumeClaims'},
+            {type: 'storageclass', label: 'StorageClasses'},
+        ],
+    },
+    {
+        name: 'configuration',
+        label: 'Configuration',
+        resources: [
+            {type: 'configmap', label: 'ConfigMaps'},
+            {type: 'secret', label: 'Secrets'},
+        ],
+    },
+];
+
 export default adapter<IConfig>(({utError}) => {
     _errors ||= utError.register(errorMap);
 
@@ -318,6 +363,29 @@ export default adapter<IConfig>(({utError}) => {
             };
 
             try {
+                // Commander explorer navigation levels (synthetic, no cluster calls):
+                //   `{ns}.category.list`  → the resource categories
+                //   `{ns}.resource.list`  → the resource types within a category
+                if (_resourceType === 'category' && operation === 'list') {
+                    const ns =
+                        (!Array.isArray(params) && params.namespace) ||
+                        this.config.k8s.namespace ||
+                        'default';
+                    return {items: CATEGORIES.map(c => ({category: c.name, label: c.label, namespace: ns}))};
+                }
+                if (_resourceType === 'resource' && operation === 'list') {
+                    const category =
+                        !Array.isArray(params) ? (params.category as string | undefined) : undefined;
+                    const ns =
+                        (!Array.isArray(params) && params.namespace) ||
+                        this.config.k8s.namespace ||
+                        'default';
+                    const cat = CATEGORIES.find(c => c.name === category);
+                    const resources = cat?.resources ?? [];
+                    return {
+                        items: resources.map(r => ({resourceType: r.type, label: r.label, namespace: ns})),
+                    };
+                }
                 switch (operation) {
                     case 'get': {
                         // Get single resource
@@ -351,6 +419,28 @@ export default adapter<IConfig>(({utError}) => {
                             ...(continueToken && {continue: continueToken}),
                         });
                     }
+                    case 'log': {
+                        // Read pod container logs (`{ns}.pod.log`)
+                        if (Array.isArray(params)) {
+                            throw this.error(_errors['k8s.invalid'](), $meta);
+                        }
+                        if (resourceType !== 'pod') {
+                            throw this.error(_errors['k8s.invalid'](), $meta);
+                        }
+                        const {name, container, tailLines, sinceSeconds, follow = false} = params;
+                        if (!name) {
+                            throw this.error(_errors['k8s.missingKey']({key: 'name'}), $meta);
+                        }
+                        const result = await this.config.context.coreV1Api!.readNamespacedPodLog({
+                            name: name as string,
+                            namespace,
+                            container: container as string | undefined,
+                            follow: follow as boolean,
+                            tailLines: tailLines as number | undefined,
+                            sinceSeconds: sinceSeconds as number | undefined,
+                        });
+                        return {logs: result};
+                    }
                     case 'create':
                     case 'add': {
                         // Create resource

package/src/adapter/server/kafka.ts

@@ -1,5 +1,5 @@
-import {adapter} from '@feasibleone/blong/types';
-import Kafka from 'node-rdkafka';
+import {adapter, type IMeta} from '@feasibleone/blong/types';
+import Kafka, {type Message} from 'node-rdkafka';
 import {Duplex} from 'stream';
 
 type KafkaConfig = ConstructorParameters<typeof Kafka.KafkaConsumer>[0];
@@ -18,6 +18,18 @@ export interface IConfig {
     codec?: {
         new (config: object): CodecInstance;
     };
+    /**
+     * Operation mode.
+     * - `'stream'` (default): a produce/consume message adapter — every triple
+     *   is routed through the Kafka stream (the request is encoded and produced
+     *   to `consume.topics`, the response is consumed + decoded). This is the
+     *   original design for message round-trips.
+     * - `'admin'`: an introspection adapter — triples are routed to `exec`
+     *   (like the API adapters: `super.connect()` → `handle()` → `exec`), so
+     *   `{ns}.topic.list` (broker metadata) and `{ns}.topic.find` (message
+     *   reads via one-off consumers) are reachable. No produce/consume stream.
+     */
+    mode?: 'stream' | 'admin';
 }
 
 export default adapter<IConfig>(() => {
@@ -30,6 +42,13 @@ export default adapter<IConfig>(() => {
                   isConnected(): boolean;
                   once(event: 'ready', cb: () => void): void;
                   assignments(): {partition: number; topic: string; offset: number}[];
+                  getMetadata(
+                      opts: {timeout: number},
+                      cb: (
+                          err: Error | null,
+                          data?: {topics?: Array<{name: string; partitions: unknown[]}>},
+                      ) => void,
+                  ): void;
               };
           })
         | null = null;
@@ -49,7 +68,12 @@ export default adapter<IConfig>(() => {
         async start() {
             const result = await super.start();
 
-            if (this.config.codec) {
+            const isAdmin = this.config.mode === 'admin';
+            // The codec encodes/decodes the Kafka stream message format. Admin
+            // (introspection) mode routes triples to `exec` (plain object
+            // responses), so the codec must NOT be applied there — a stream
+            // codec would try `msg.value.toString()` on the exec result.
+            if (this.config.codec && !isAdmin) {
                 codec = new this.config.codec({});
                 this.encode = (...params) => codec!.encode(...params);
                 this.decode = (...params) => codec!.decode(...params);
@@ -57,11 +81,24 @@ export default adapter<IConfig>(() => {
                 codec = null;
             }
 
-            consumerStream = Kafka.KafkaConsumer.createReadStream(
+            const groupId = this.config.consume.groupId;
+            const startedAt = Date.now();
+            const consumerConfig = {
+                ...this.config.connection,
+                'group.id': groupId,
+            };
+            this.log?.info?.(
                 {
-                    ...this.config.connection,
-                    'group.id': this.config.consume.groupId,
+                    groupId,
+                    topics: this.config.consume.topics,
+                    sessionTimeoutMs: consumerConfig['session.timeout.ms'],
+                    broker: consumerConfig['metadata.broker.list'],
                 },
+                'kafka consumer creating',
+            );
+
+            consumerStream = Kafka.KafkaConsumer.createReadStream(
+                consumerConfig,
                 {
                     'auto.offset.reset': 'earliest',
                 },
@@ -83,49 +120,93 @@ export default adapter<IConfig>(() => {
                     poll = setInterval(() => {
                         if (consumerStream!.consumer.assignments().length > 0) {
                             cleanup();
+                            this.log?.info?.(
+                                {groupId, elapsedMs: Date.now() - startedAt},
+                                'kafka consumer assigned',
+                            );
                             resolve();
                         }
                     }, 200);
                     safety = setTimeout(() => {
                         cleanup();
+                        this.log?.warn?.(
+                            {
+                                groupId,
+                                elapsedMs: Date.now() - startedAt,
+                                hint: 'stale group members from an earlier abrupt shutdown keep the rebalance waiting up to session.timeout.ms',
+                            },
+                            'kafka consumer assignment timed out',
+                        );
+                        // Best-effort graceful close BEFORE failing start: a
+                        // consumer that joined the group but never got an
+                        // assignment would otherwise linger as a stale group
+                        // member (no LeaveGroup), blocking the NEXT rebalance
+                        // for up to session.timeout.ms too. destroy() →
+                        // close() → disconnect() sends LeaveGroup.
+                        try {
+                            consumerStream?.destroy();
+                        } catch {
+                            // ignore — the process is already failing start
+                        }
                         reject(new Error('Kafka assignment timeout'));
                     }, 30000);
                 };
                 if (consumerStream!.consumer.isConnected()) {
+                    this.log?.info?.({groupId}, 'kafka consumer already connected');
                     startPolling();
                 } else {
-                    consumerStream!.consumer.once('ready', startPolling);
+                    this.log?.info?.({groupId}, 'kafka consumer connecting, waiting for ready');
+                    consumerStream!.consumer.once('ready', () => {
+                        this.log?.info?.(
+                            {groupId, elapsedMs: Date.now() - startedAt},
+                            'kafka consumer ready',
+                        );
+                        startPolling();
+                    });
                 }
             });
 
-            producerStream = Kafka.Producer.createWriteStream(
-                {
-                    ...this.config.connection,
-                },
-                {},
-                {
-                    objectMode: true,
-                },
-            );
+            if (this.config.mode === 'admin') {
+                // Admin/introspection mode — route triples to `exec`
+                // (`super.connect()` → `handle()` → `findHandler(method) ||
+                // imported['exec']`). The consumer stays connected for broker
+                // metadata (`{ns}.topic.list` uses `getMetadata`); the
+                // produce/consume Duplex is not built and no messages are
+                // consumed by this adapter instance.
+                super.connect();
+            } else {
+                producerStream = Kafka.Producer.createWriteStream(
+                    {
+                        ...this.config.connection,
+                    },
+                    {},
+                    {
+                        objectMode: true,
+                    },
+                );
 
-            // Build a custom Duplex that writes to the Kafka producer and
-            // receives messages from the Kafka consumer via 'data' events.
-            // Duplex.from({readable, writable}) is not used because it does
-            // not reliably forward object-mode events from the inner readable.
-            stream = new Duplex({objectMode: true, read() {}});
-            stream.write = (chunk, ...args) =>
-                (producerStream!.write as (...a: unknown[]) => boolean)(chunk, ...args);
+                // Build a custom Duplex that writes to the Kafka producer and
+                // receives messages from the Kafka consumer via 'data' events.
+                // Duplex.from({readable, writable}) is not used because it does
+                // not reliably forward object-mode events from the inner readable.
+                stream = new Duplex({objectMode: true, read() {}});
+                stream.write = (chunk, ...args) =>
+                    (producerStream!.write as (...a: unknown[]) => boolean)(chunk, ...args);
 
-            consumerStream!.on('data', msg => stream?.push(msg));
-            consumerStream!.on('end', () => stream?.push(null));
-            consumerStream!.on('error', err => stream?.destroy(err as Error));
+                consumerStream!.on('data', msg => stream?.push(msg));
+                consumerStream!.on('end', () => stream?.push(null));
+                consumerStream!.on('error', err => stream?.destroy(err as Error));
 
-            super.connect(stream);
+                super.connect(stream);
+            }
 
             return result;
         },
 
         async stop(...params: unknown[]) {
+            const groupId = this.config.consume.groupId;
+            const stopStartedAt = Date.now();
+            this.log?.info?.({groupId}, 'kafka adapter stop');
             const awaitClose = (
                 s: {once(e: 'close', cb: () => void): void} | null,
                 disconnect: () => void,
@@ -134,9 +215,27 @@ export default adapter<IConfig>(() => {
                 !s
                     ? Promise.resolve()
                     : new Promise<void>(resolve => {
-                          const t = setTimeout(resolve, ms);
+                          const t = setTimeout(() => {
+                              this.log?.warn?.(
+                                  {
+                                      groupId,
+                                      waitMs: ms,
+                                      elapsedMs: Date.now() - stopStartedAt,
+                                      hint: 'consumer/producer did not emit close — the group member was not gracefully removed',
+                                  },
+                                  'kafka close timed out',
+                              );
+                              resolve();
+                          }, ms);
                           s.once('close', () => {
                               clearTimeout(t);
+                              this.log?.info?.(
+                                  {
+                                      groupId,
+                                      elapsedMs: Date.now() - stopStartedAt,
+                                  },
+                                  'kafka consumer/producer closed (LeaveGroup sent)',
+                              );
                               resolve();
                           });
                           disconnect();
@@ -156,6 +255,10 @@ export default adapter<IConfig>(() => {
                         20000,
                     ),
                 ]);
+                this.log?.info?.(
+                    {groupId, elapsedMs: Date.now() - stopStartedAt},
+                    'kafka adapter stop complete',
+                );
             } finally {
                 stream = null;
                 codec = null;
@@ -165,5 +268,103 @@ export default adapter<IConfig>(() => {
             }
             return result;
         },
+
+        async exec(
+            params: Record<string, unknown>,
+            $meta: IMeta,
+        ): Promise<unknown> {
+            const {method} = $meta;
+            const [, object, operation] = method!.split('.');
+            if (object === 'topic') {
+                switch (operation) {
+                    case 'list': {
+                        // `{ns}.topic.list` — enumerate topics from broker metadata
+                        if (!consumerStream) {
+                            throw new Error('Kafka consumer not connected');
+                        }
+                        const metadata = await new Promise<{
+                            topics: Array<{name: string; partitions: unknown[]}>;
+                        }>((resolve, reject) => {
+                            consumerStream!.consumer.getMetadata(
+                                {timeout: 5000, allTopics: true},
+                                (err, data) => (err ? reject(err) : resolve(data ?? {topics: []})),
+                            );
+                        });
+                        return {
+                            items: (metadata.topics ?? [])
+                                .filter(t => !t.name.startsWith('__'))
+                                .map(t => ({
+                                    topic: t.name,
+                                    partitionCount: t.partitions?.length ?? 0,
+                                })),
+                        };
+                    }
+                    case 'find': {
+                        // `{ns}.topic.find` — read a batch of messages from a topic.
+                        // A fresh consumer group with `auto.offset.reset: earliest`
+                        // reads existing messages from the beginning (exploration);
+                        // partitions are surfaced as message metadata, not tree nodes.
+                        const topic = params.topic as string;
+                        const limit = (params.limit as number) ?? 50;
+                        if (!topic) {
+                            throw new Error('Missing topic param');
+                        }
+                        const consumer = new Kafka.KafkaConsumer(
+                            {
+                                ...this.config.connection,
+                                'group.id': `blong-commander-${Date.now()}`,
+                            },
+                            {'auto.offset.reset': 'earliest'},
+                        );
+                        // A fresh group must complete the rebalance (group join +
+                        // partition assignment) before the first consume returns.
+                        consumer.setDefaultConsumeTimeout(3000);
+                        // Always RESOLVE to a (possibly empty) batch — a rebalance
+                        // stall or broker hiccup must surface as an empty topic, not
+                        // as a malformed/empty RPC response ("JSON RPC response
+                        // without response and error").
+                        const messages = await new Promise<Message[] | undefined>(resolve => {
+                            const timer = setTimeout(() => {
+                                try {
+                                    consumer.disconnect();
+                                } catch {
+                                    // ignore
+                                }
+                                resolve(undefined);
+                            }, 15000);
+                            const done = (msgs: Message[] | undefined) => {
+                                clearTimeout(timer);
+                                try {
+                                    consumer.disconnect();
+                                } catch {
+                                    // ignore
+                                }
+                                resolve(msgs);
+                            };
+                            consumer.on('ready', () => {
+                                consumer.subscribe([topic]);
+                                consumer.consume(limit, (err, msgs) => {
+                                    if (err) return done(undefined);
+                                    done(msgs);
+                                });
+                            });
+                            consumer.on('event.error', () => done(undefined));
+                            consumer.connect();
+                        });
+                        return {
+                            items: (messages ?? []).map(m => ({
+                                topic: m.topic,
+                                partition: m.partition,
+                                offset: m.offset,
+                                key: m.key?.toString(),
+                                value: m.value?.toString(),
+                                timestamp: m.timestamp,
+                            })),
+                        };
+                    }
+                }
+            }
+            throw new Error(`Unknown kafka operation: ${object}.${operation}`);
+        },
     };
 });

package/src/adapter/server/knex.ts

@@ -407,6 +407,51 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
                     this as unknown as {_dropdownList(s: string): Promise<unknown>}
                 )._dropdownList(subject);
             }
+            // Structure discovery for the commander explorer:
+            //   `{ns}.schema.list` — databases/schemas on the server
+            //   `{ns}.table.list`  — tables in a schema (params.schema)
+            if (object === 'schema' && operation === 'list') {
+                const qb = this.config.context.queryBuilder!;
+                const rows = await qb
+                    .select('SCHEMA_NAME as schemaName')
+                    .from('information_schema.schemata')
+                    .orderBy('SCHEMA_NAME');
+                return {items: rows as Array<{schemaName: string}>};
+            }
+            if (object === 'table' && operation === 'list') {
+                const qb = this.config.context.queryBuilder!;
+                // When no schema is given, scope to the adapter's own database so
+                // the explorer lists the app's tables only — not every schema the
+                // connection can see (information_schema, mysql, other realms' DBs).
+                const schema = (params as Record<string, unknown>).schema as string | undefined;
+                const database =
+                    schema ?? (this.config.knex?.connection as {database?: string} | undefined)?.database;
+                let query = qb
+                    .select('TABLE_NAME as tableName', 'TABLE_TYPE as tableType')
+                    .from('information_schema.tables')
+                    .orderBy('TABLE_NAME');
+                if (database) query = query.where('TABLE_SCHEMA', database);
+                const rows = await query;
+                // Drop leftover template/placeholder tables (e.g. `$subject_$object`
+                // from an unresolved schema seed) — they are not real, queryable
+                // tables and clicking them would surface a "table doesn't exist".
+                const junk = /[\${}]/;
+                // Only the tables this subject owns (`{subject}_*`) are reachable
+                // via the generic `{subject}.{object}` CRUD triples; strip the
+                // `{subject}_` prefix so `access.{tableName}.find` resolves to the
+                // actual table (`access.user.find` → `access_user`), instead of
+                // double-prefixing (`access.access_user.find` → `access_access_user`).
+                const prefix = `${subject}_`;
+                return {
+                    items: (rows as Array<{tableName: string; tableType: string}>)
+                        .filter(row => !junk.test(row.tableName))
+                        .filter(row => row.tableName.startsWith(prefix))
+                        .map(row => ({
+                            tableName: row.tableName.slice(prefix.length),
+                            tableType: row.tableType,
+                        })),
+                };
+            }
             const table = `${subject}_${object}`;
             switch (operation) {
                 case 'get': {

package/src/adapter/server/mongodb.ts

@@ -70,12 +70,18 @@ export default adapter<IConfig>(({utError}) => {
             const {method} = $meta;
             const [, _table, operation] = method!.split('.');
             let table = _table;
+            let dbName: string | undefined;
+            // `{ns}.collection.*` triples carry `{database, collection}`; the
+            // collection is the table, the database selects the DB (and must NOT
+            // leak into the WHERE filter — previously docs were filtered by a
+            // literal `database` field, yielding empty lists).
             if (!Array.isArray(params) && _table === 'collection') {
-                const {collection, ...rest} = params;
+                const {collection, database, ...rest} = params;
                 if (collection) {
                     table = collection;
                     params = rest;
                 }
+                dbName = database as string | undefined;
             }
             const key = table.split(/\W/, 1)[0] + 'Id';
             switch (operation) {
@@ -86,8 +92,8 @@ export default adapter<IConfig>(({utError}) => {
                     }
                     const nonArrayParams = params as Record<string, unknown>;
                     const {select = '*', sort, [key]: _id, ...where} = nonArrayParams;
-                    return this.config.context
-                        .mongodb!.db()
+                    const doc = await this.config.context
+                        .mongodb!.db(dbName)
                         .collection(table)
                         .findOne(
                             {
@@ -108,6 +114,11 @@ export default adapter<IConfig>(({utError}) => {
                                 sort: sort as import('mongodb').Sort | undefined,
                             },
                         );
+                    // Surface a string `id` (mongo's `_id` is an ObjectId object,
+                    // dropped by the commander's scalar-only flattening).
+                    return doc
+                        ? {...doc, id: String((doc as {_id?: unknown})._id ?? '')}
+                        : doc;
                 }
                 case 'find': {
                     // find multiple documents
@@ -115,8 +126,8 @@ export default adapter<IConfig>(({utError}) => {
                         throw this.error(_errors['mongodb.invalid'](), $meta);
                     }
                     const {select = '*', order, limit, offset, [key]: _id, ...where} = params;
-                    return this.config.context
-                        .mongodb!.db()
+                    const docs = await this.config.context
+                        .mongodb!.db(dbName)
                         .collection(table)
                         .find(
                             {
@@ -152,6 +163,8 @@ export default adapter<IConfig>(({utError}) => {
                             },
                         )
                         .toArray();
+                    // Surface a string `id` for the commander explorer rows.
+                    return docs.map(doc => ({...doc, id: String((doc as {_id?: unknown})._id ?? '')}));
                 }
                 case 'add': {
                     // add single document
@@ -234,6 +247,47 @@ export default adapter<IConfig>(({utError}) => {
                         .mongodb!.db()
                         .collection(table)
                         .deleteMany(params as Filter<BSON.Document>);
+                case 'list': {
+                    // Enumeration for the commander explorer:
+                    //   `{ns}.database.list`   → databases on the server
+                    //   `{ns}.collection.list` → collections in a database (params.database)
+                    if (Array.isArray(params)) {
+                        throw this.error(_errors['mongodb.invalid'](), $meta);
+                    }
+                    if (_table === 'database') {
+                        const result = await this.config.context
+                            .mongodb!.db()
+                            .admin()
+                            .listDatabases();
+                        return {
+                            items:
+                                result.databases?.map(db => ({
+                                    database: db.name,
+                                    sizeOnDisk: db.sizeOnDisk,
+                                    empty: db.empty,
+                                })) ?? [],
+                        };
+                    }
+                    if (_table === 'collection') {
+                        const database = (params as Record<string, unknown>).database as
+                            | string
+                            | undefined;
+                        const collections = await this.config.context
+                            .mongodb!.db(database)
+                            .listCollections()
+                            .toArray();
+                        return {
+                            items: collections.map(c => ({
+                                collection: c.name,
+                                type: c.type,
+                                // thread the DB so deeper levels can resolve
+                                // `{parent.database}`
+                                database,
+                            })),
+                        };
+                    }
+                    throw this.error(_errors['mongodb.invalid'](), $meta);
+                }
             }
             throw this.error(_errors['mongodb.generic'](), $meta);
         },

package/src/adapter/server/redis.ts

@@ -1,7 +1,6 @@
-import type {IMeta, Adapter} from '@feasibleone/blong/types';
+import type {Adapter, IMeta} from '@feasibleone/blong/types';
 import {adapter, type Errors, type IErrorMap} from '@feasibleone/blong/types';
-import Redis from 'ioredis';
-import {Cluster} from 'ioredis';
+import Redis, {Cluster} from 'ioredis';
 
 export interface IConfig {
     /**
@@ -49,6 +48,7 @@ export interface IRedisClient {
     hincrby(key: string, field: string, increment: number): Promise<number>;
     hdel(key: string, ...fields: string[]): Promise<number>;
     eval(script: string, numKeys: number, ...keysAndArgs: unknown[]): Promise<unknown>;
+    scan(cursor: string, ...args: unknown[]): Promise<[string, string[]]>;
     quit(): Promise<unknown>;
 }
 
@@ -121,6 +121,20 @@ export default adapter<IConfig>(({utError}) => {
             expired: (await redis.expire(params.keyName as string, params.seconds as number)) === 1,
         }),
         ttl: async params => ({ttl: await redis.ttl(params.keyName as string)}),
+        list: async params => {
+            const pattern = (params.pattern as string) ?? '*';
+            const count = (params.count as number) ?? 100;
+            const limit = (params.limit as number) ?? 1000;
+            const cursor = (params.cursor as string) ?? '0';
+            const keyNames: string[] = [];
+            let next = cursor;
+            do {
+                const [newCursor, batch] = await redis.scan(next, 'MATCH', pattern, 'COUNT', count);
+                keyNames.push(...batch);
+                next = newCursor;
+            } while (next !== '0' && keyNames.length < limit);
+            return {items: keyNames.slice(0, limit).map(keyName => ({keyName})), cursor: next};
+        },
     };
 
     // Generic hash operations: redis.hash.getAll|get|set|incrBy|del
@@ -185,6 +199,15 @@ export default adapter<IConfig>(({utError}) => {
             } catch {
                 // Best-effort: a lazy client that never connected may reject quit().
             }
+            try {
+                // `quit()` waits for the QUIT round-trip and can leave the socket
+                // open when the client is mid-connect/reconnect (the commander tap
+                // test observed a lingering 6379 socket after stop). `disconnect()`
+                // force-closes without waiting, guaranteeing the handle is released.
+                (redis as {disconnect?: () => void})?.disconnect?.();
+            } catch {
+                // ignore
+            }
             return super.stop();
         },
         /**
@@ -194,8 +217,7 @@ export default adapter<IConfig>(({utError}) => {
         async configChanged(diff: Map<string, {prev: unknown; next: unknown}>, next: unknown) {
             const redisChanged = Array.from(diff.keys()).some(
                 (key: string) =>
-                    key === this.config.id + '.redis' ||
-                    key.startsWith(this.config.id + '.redis.'),
+                    key === this.config.id + '.redis' || key.startsWith(this.config.id + '.redis.'),
             );
             if (!redisChanged) return;
             const newAdapterConfig = (next as Record<string, unknown>)?.[this.config.id] as
@@ -217,6 +239,12 @@ export default adapter<IConfig>(({utError}) => {
             const operation = parts[2];
             try {
                 await ensureConnected();
+                // `{ns}.database.list` — enumerate the logical databases this
+                // source exposes (the configured db index).
+                if (object === 'database' && operation === 'list') {
+                    const db = (this.config as {redis?: IConfig}).redis?.db ?? 0;
+                    return {items: [{db}]};
+                }
                 const ops =
                     object === 'key'
                         ? keyOps

package/src/adapter/server/s3.ts

@@ -3,6 +3,7 @@ import {
     DeleteObjectCommand,
     GetObjectCommand,
     HeadObjectCommand,
+    ListBucketsCommand,
     ListObjectsV2Command,
     PutObjectCommand,
     S3Client,
@@ -89,7 +90,7 @@ export default adapter<IConfig>(({utError}) => {
             $meta: IMeta,
         ) {
             const {method} = $meta;
-            const [, , operation] = method!.split('.');
+            const [, object, operation] = method!.split('.');
             let bucket: string | undefined;
             let actualParams = params;
 
@@ -99,7 +100,10 @@ export default adapter<IConfig>(({utError}) => {
                 actualParams = rest;
             }
 
-            if (!bucket && !this.config.bucket?.Bucket) {
+            // Bucket enumeration (`s3.bucket.list`) does not need a target bucket.
+            const needsBucket =
+                !(object === 'bucket' && (operation === 'list' || operation === 'find'));
+            if (!bucket && !this.config.bucket?.Bucket && needsBucket) {
                 throw this.error(_errors['s3.missingBucket'](), $meta);
             }
 
@@ -203,6 +207,18 @@ export default adapter<IConfig>(({utError}) => {
                     if (Array.isArray(actualParams)) {
                         throw this.error(_errors['s3.invalid'](), $meta);
                     }
+                    // `s3.bucket.list` — enumerate buckets on the endpoint
+                    if (object === 'bucket') {
+                        const command = new ListBucketsCommand({});
+                        const response = await this.config.context.s3!.send(command);
+                        return {
+                            items:
+                                response.Buckets?.map(b => ({
+                                    bucket: b.Name,
+                                    creationDate: b.CreationDate,
+                                })) ?? [],
+                        };
+                    }
                     const {prefix, maxKeys = 1000} = actualParams;
 
                     const command = new ListObjectsV2Command({

package/src/adapter/server/vault.ts

@@ -32,6 +32,25 @@ const errorMap: IErrorMap = {
 
 let _errors: Errors<typeof errorMap>;
 
+// KV v2 secret-engine mount paths (trailing slash, e.g. `secret/`), discovered
+// from `vault.mount.list`. KV v2 stores the actual secrets under `metadata/`
+// (listing) / `data/` (reading) instead of the mount root.
+const kv2Mounts = new Set<string>();
+
+/** Collapse doubled separators from `{parent.path}/{key}` joins. */
+function normalizePath(path: string): string {
+    return path.replace(/\/{2,}/g, '/');
+}
+
+/** The KV v2 mount a path belongs to (e.g. `secret/`), or null. */
+function kv2MountFor(path: string): string | null {
+    const normalized = normalizePath(path);
+    for (const mount of kv2Mounts) {
+        if (normalized === mount || normalized.startsWith(mount)) return mount;
+    }
+    return null;
+}
+
 async function authenticateVault(this: {config: IConfig}): Promise<void> {
     const {authMethod, roleId, secretId, username, password} = this.config.vault;
 
@@ -155,9 +174,27 @@ export default adapter<IConfig>(({utError}) => {
                         throw this.error(_errors['vault.missingPath'](), $meta);
                     }
 
+                    // KV v2: secrets are read from `<mount>data/<name>`, and the
+                    // secret fields are wrapped under `data`.
+                    let readPath = normalizePath(secretPath);
+                    const mount = kv2MountFor(readPath);
+                    if (mount && !readPath.startsWith(`${mount}data/`)) {
+                        const name = readPath.slice(mount.length);
+                        readPath = `${mount}data/${name}`;
+                    }
+
                     try {
-                        const result = await this.config.context.vault!.read(secretPath);
-                        return result.data;
+                        const result = await this.config.context.vault!.read(readPath);
+                        const payload = result.data;
+                        if (
+                            payload &&
+                            typeof payload === 'object' &&
+                            !Array.isArray(payload) &&
+                            'data' in payload
+                        ) {
+                            return (payload as {data: unknown}).data;
+                        }
+                        return payload;
                     } catch (error: unknown) {
                         throw this.error(
                             (error as {response?: {statusCode?: number}})?.response?.statusCode === 404
@@ -220,19 +257,74 @@ export default adapter<IConfig>(({utError}) => {
                     if (Array.isArray(actualParams)) {
                         throw this.error(_errors['vault.invalid'](), $meta);
                     }
+                    // `vault.mount.list` — enumerate mounted secret engines
+                    if (resource === 'mount') {
+                        try {
+                            const result = await this.config.context.vault!.mounts();
+                            kv2Mounts.clear();
+                            const items = Object.entries(result?.data ?? {}).map(
+                                ([path, cfg]: [string, unknown]) => {
+                                    const c = cfg as {
+                                        type?: string;
+                                        options?: {version?: number};
+                                    };
+                                    if (c?.type === 'kv' && (c.options?.version ?? 0) === 2) {
+                                        kv2Mounts.add(path);
+                                    }
+                                    return {
+                                        path,
+                                        ...(typeof cfg === 'object' && cfg !== null
+                                            ? (cfg as Record<string, unknown>)
+                                            : {}),
+                                    };
+                                },
+                            );
+                            return {items};
+                        } catch (error: unknown) {
+                            throw this.error(_errors['vault.generic'](error), $meta);
+                        }
+                    }
                     if (!secretPath) {
                         throw this.error(_errors['vault.missingPath'](), $meta);
                     }
 
+                    // KV v2: a mount root (or its `data/` marker) lists the actual
+                    // secrets through `metadata/` — never the raw mount root.
+                    const originalPath = normalizePath(secretPath);
+                    let listPath = originalPath;
+                    const mount = kv2MountFor(listPath);
+                    if (mount) {
+                        const trimmedMount = mount.replace(/\/+$/, '');
+                        const trimmedList = listPath.replace(/\/+$/, '');
+                        if (trimmedList === trimmedMount || trimmedList === `${trimmedMount}/data`) {
+                            listPath = `${trimmedMount}/metadata/`;
+                        }
+                    }
+
                     try {
-                        const result = await this.config.context.vault!.list(secretPath);
-                        return result.data;
+                        const result = await this.config.context.vault!.list(listPath);
+                        const data = (result.data ?? {}) as {keys?: string[]};
+                        // Keep the native Vault `keys` shape (relied on by the
+                        // integration tests) and additionally expose commander-style
+                        // `items` rows (consistent with `vault.mount.list`) so the
+                        // generic explorer can render the secrets as a table. Keys
+                        // ending in `/` are sub-path (directory) markers, not leaf
+                        // secrets — clicking one would 404 ("Vault Secret Not
+                        // Found"), so they are filtered out. Rows carry the MOUNT
+                        // path so the deeper level's `{parent.path}/{key}` open
+                        // resolves to `<mount>/<name>`.
+                        const keys = (data.keys ?? []).filter(key => !key.endsWith('/'));
+                        return {
+                            ...data,
+                            keys,
+                            items: keys.map(key => ({key, path: originalPath})),
+                        };
                     } catch (error: unknown) {
                         if (
                             (error as {response?: {statusCode?: number}})?.response?.statusCode ===
                             404
                         ) {
-                            return {keys: []};
+                            return {keys: [], items: []};
                         }
                         throw this.error(_errors['vault.generic'](error), $meta);
                     }

package/template/playwright.config.ts

@@ -1,7 +1,3 @@
 import {defineBlongConfig} from '@feasibleone/blong-browser/playwright/config';
 
-export default defineBlongConfig({
-    // Adjust these ports if they clash with another locally-running realm.
-    backendPort: 9003,
-    frontendPort: 9103,
-});
+export default defineBlongConfig();