@feasibleone/blong-gogo 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.22.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.21.0...blong-gogo-v1.22.0) (2026-05-14)
+
+
+### Features
+
+* intents ([5b238b0](https://github.com/feasibleone/blong/commit/5b238b064be7e20a051e963f23762012ce96bcb9))
+
+
+### Bug Fixes
+
+* improve integration test coverage for keycloak, S3, and vault adapters ([#149](https://github.com/feasibleone/blong/issues/149)) ([453c9ac](https://github.com/feasibleone/blong/commit/453c9ac17bdde48c526d92e465aeeb6a6fd816bb))
+* integration tests coverage report ([ce3ae79](https://github.com/feasibleone/blong/commit/ce3ae79e8056fab2d09d5f0779f24997773ba3c8))
+* integration tests coverage report ([4215fc1](https://github.com/feasibleone/blong/commit/4215fc1a8620e3cf36d748f55aabb0c85917d2f2))
+* integration tests coverage report ([bb8d3c7](https://github.com/feasibleone/blong/commit/bb8d3c7b0eb64c6be9d90d70ac1469c065139f31))
+
 ## [1.21.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.20.0...blong-gogo-v1.21.0) (2026-05-12)
 
 

package/bin/blong-dev.ts

@@ -1,8 +1,15 @@
 #!/usr/bin/env -S node --watch --conditions=development --inspect
 
 import minimist from 'minimist';
+import {existsSync} from 'node:fs';
+import {resolve} from 'node:path';
 import {autoRun} from '../src/runServer.ts';
 
 const argv: {_: string[]} = minimist(process.argv.slice(2));
 
-await autoRun({cwd: process.cwd(), target: argv._[0]});
+// The first positional arg is an optional file/folder target; the rest are intents.
+const [maybeTarget, ...rest] = argv._;
+const target = maybeTarget && existsSync(resolve(maybeTarget)) ? maybeTarget : undefined;
+const intents = target ? rest : argv._;
+
+await autoRun({cwd: process.cwd(), target, intents});

package/bin/blong.ts

@@ -1,8 +1,15 @@
 #!/usr/bin/env -S node
 
 import minimist from 'minimist';
+import {existsSync} from 'node:fs';
+import {resolve} from 'node:path';
 import {autoRun} from '../src/runServer.ts';
 
 const argv: {_: string[]} = minimist(process.argv.slice(2));
 
-await autoRun({cwd: process.cwd(), target: argv._[0]});
+// The first positional arg is an optional file/folder target; the rest are intents.
+const [maybeTarget, ...rest] = argv._;
+const target = maybeTarget && existsSync(resolve(maybeTarget)) ? maybeTarget : undefined;
+const intents = target ? rest : argv._;
+
+await autoRun({cwd: process.cwd(), target, intents});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },
@@ -84,6 +84,7 @@
     "build": "true",
     "ci-lint": "tsc --noEmit",
     "ci-publish": "node ../../common/scripts/install-run-rush-pnpm.js publish --access public --provenance",
-    "ci-unit": "tap src/ConfigRuntime.test.ts src/lib.test.ts --allow-incomplete-coverage"
+    "ci-unit": "../common/run-coverage.sh",
+    "ci-coverage": "../common/run-coverage.sh report"
   }
 }

package/src/adapter/server/keycloak.ts

@@ -249,7 +249,7 @@ export default adapter<IConfig>(({utError}) => {
 
                         case 'update':
                         case 'edit': {
-                            const {id: userId, ...updateData} = handleParams;
+                            const {id: userId, realm: _realm, ...updateData} = handleParams;
                             if (!userId) throw _errors['keycloak.missingKey']({key: 'id'});
                             return await client.users.update({id: userId as string}, updateData);
                         }
@@ -368,7 +368,7 @@ export default adapter<IConfig>(({utError}) => {
 
                         case 'update':
                         case 'edit': {
-                            const {id: groupId, ...updateData} = handleParams;
+                            const {id: groupId, realm: _realm, ...updateData} = handleParams;
                             if (!groupId) throw _errors['keycloak.missingKey']({key: 'id'});
                             return await client.groups.update({id: groupId as string}, updateData);
                         }
@@ -483,6 +483,7 @@ export default adapter<IConfig>(({utError}) => {
                             const {
                                 roleName: updateRoleName,
                                 clientUuid: updateClientUuid,
+                                realm: _realm,
                                 ...updateData
                             } = handleParams;
                             if (!updateRoleName)
@@ -499,7 +500,7 @@ export default adapter<IConfig>(({utError}) => {
                             } else {
                                 return await client.roles.updateByName(
                                     {name: updateRoleName as string},
-                                    updateData,
+                                    {name: updateRoleName as string, ...updateData},
                                 );
                             }
                         }
@@ -614,7 +615,11 @@ export default adapter<IConfig>(({utError}) => {
 
                         case 'update':
                         case 'edit': {
-                            const {id: clientUpdateId, ...clientUpdateData} = handleParams;
+                            const {
+                                id: clientUpdateId,
+                                realm: _realm,
+                                ...clientUpdateData
+                            } = handleParams;
                             if (!clientUpdateId) throw _errors['keycloak.missingKey']({key: 'id'});
                             return await client.clients.update(
                                 {id: clientUpdateId as string},
@@ -762,6 +767,8 @@ export default adapter<IConfig>(({utError}) => {
                         throw _errors['keycloak.invalid']();
                 }
             } catch (error: unknown) {
+                // Re-throw already-typed blong errors without wrapping them
+                if (typeof (error as {type?: string}).type === 'string') throw error;
                 const keycloakError = error as {
                     response?: {status?: number; data?: {error?: string}};
                 };

package/src/jose.test.ts

@@ -1,5 +1,5 @@
 import assert from 'node:assert';
-import {test} from 'node:test';
+import {test} from 'tap';
 
 import jose from './jose.ts';
 

package/src/jose.ts

@@ -269,7 +269,7 @@ export default async function jose({sign, encrypt}: {sign?: KeySpec; encrypt?: K
                 ? signEncrypt(
                       msg,
                       mlsk,
-                      await importKey(key),
+                      await importKey(await exportKey(key as JWK)),
                       protectedHeader!,
                       unprotectedHeader!,
                       options,
@@ -278,7 +278,7 @@ export default async function jose({sign, encrypt}: {sign?: KeySpec; encrypt?: K
         decryptVerify: async (
             msg: Parameters<typeof decryptVerify>[0],
             key: Parameters<typeof importKey>[0],
-        ) => (mlek ? decryptVerify(msg, await importKey(key), mlek!) : msg),
+        ) => (mlek ? decryptVerify(msg, await importKey(await exportKey(key as JWK)), mlek!) : msg),
         decrypt: (msg, options) =>
             mlek ? decrypt(msg, mlek!, options as {complete?: unknown} | undefined) : msg,
         verify: async (msg, key) => verify(msg, await importKey(key)),

package/src/loadServer.ts

@@ -28,6 +28,12 @@ const loadConfig = async (parentConfig: string | object) => {
     return {loadedConfig, configRuntime};
 };
 
+// Parse CLI intents: first positional arg may be a file/folder target — exclude it from intents.
+const allPositional = minimist(process.argv.slice(2))._ as string[];
+const [maybeTarget, ...rest] = allPositional;
+const targetIsFile = Boolean(maybeTarget && existsSync(resolve(maybeTarget)));
+const cliIntents = targetIsFile ? rest : allPositional;
+
 export default load.bind(null, {
     platform: 'server',
     readdir: async (path: string) => readdir(path, {withFileTypes: true}),
@@ -46,5 +52,5 @@ export default load.bind(null, {
     statSync,
     watch,
     timing: timing(hrtime),
-    configs: ['server', ...minimist(process.argv.slice(2))._],
+    configs: ['server', ...cliIntents],
 });

package/src/runServer.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Unit tests for CLI intent parsing logic in runServer.ts.
+ *
+ * These tests verify:
+ *   - autoRun correctly separates file-path targets from intents
+ *   - runPlatform uses DEFAULT_INTENTS when no intents are provided
+ *   - DEFAULT_INTENTS matches the expected set
+ */
+
+import {test} from 'tap';
+
+import {DEFAULT_INTENTS} from './runServer.ts';
+
+// ---------------------------------------------------------------------------
+// DEFAULT_INTENTS
+// ---------------------------------------------------------------------------
+
+test('DEFAULT_INTENTS contains the three baseline intents', async t => {
+    t.same([...DEFAULT_INTENTS], ['microservice', 'integration', 'dev']);
+});
+
+// ---------------------------------------------------------------------------
+// Intent extraction helper — replicated inline to avoid FS side-effects
+// ---------------------------------------------------------------------------
+
+/**
+ * Mirrors the logic in bin/blong.ts:
+ *   - first element is the target when existsSync returns true
+ *   - remaining elements (or all elements when no target) are intents
+ */
+function extractIntents(
+    positional: string[],
+    fileExists: (path: string) => boolean,
+): {target: string | undefined; intents: string[]} {
+    const [maybeTarget, ...rest] = positional;
+    const target = maybeTarget && fileExists(maybeTarget) ? maybeTarget : undefined;
+    const intents = target ? rest : positional;
+    return {target, intents};
+}
+
+// ---------------------------------------------------------------------------
+// extractIntents — file-path as first positional
+// ---------------------------------------------------------------------------
+
+test('extractIntents — recognises existing file as target', async t => {
+    const {target, intents} = extractIntents(['./server.ts', 'integration'], () => true);
+    t.equal(target, './server.ts');
+    t.same(intents, ['integration']);
+});
+
+test('extractIntents — non-existent path is treated as an intent', async t => {
+    const {target, intents} = extractIntents(['integration', 'dev'], () => false);
+    t.equal(target, undefined);
+    t.same(intents, ['integration', 'dev']);
+});
+
+test('extractIntents — empty args yield no target and no intents', async t => {
+    const {target, intents} = extractIntents([], () => false);
+    t.equal(target, undefined);
+    t.same(intents, []);
+});
+
+test('extractIntents — single file target, no intents', async t => {
+    const {target, intents} = extractIntents(['/abs/path/server.ts'], () => true);
+    t.equal(target, '/abs/path/server.ts');
+    t.same(intents, []);
+});
+
+test('extractIntents — multiple intents with no target', async t => {
+    const {target, intents} = extractIntents(
+        ['integration', 'microservice', 'debug'],
+        () => false,
+    );
+    t.equal(target, undefined);
+    t.same(intents, ['integration', 'microservice', 'debug']);
+});
+
+test('extractIntents — multiple intents after a valid target', async t => {
+    const {target, intents} = extractIntents(
+        ['./index.ts', 'integration', 'debug'],
+        () => true,
+    );
+    t.equal(target, './index.ts');
+    t.same(intents, ['integration', 'debug']);
+});
+
+// ---------------------------------------------------------------------------
+// Intent resolution — default fallback when none provided
+// ---------------------------------------------------------------------------
+
+/**
+ * Mirrors the intent-resolution logic in autoRun:
+ *   cliIntents.length > 0  → use cliIntents
+ *   otherwise              → fall back to DEFAULT_INTENTS
+ */
+function resolveIntents(cliIntents: string[]): string[] {
+    return cliIntents.length > 0 ? cliIntents : [...DEFAULT_INTENTS];
+}
+
+test('resolveIntents — empty CLI intents fall back to defaults', async t => {
+    t.same(resolveIntents([]), [...DEFAULT_INTENTS]);
+});
+
+test('resolveIntents — provided intents are used as-is', async t => {
+    t.same(resolveIntents(['integration']), ['integration']);
+});
+
+test('resolveIntents — custom intent is passed through', async t => {
+    t.same(resolveIntents(['db']), ['db']);
+});
+
+test('resolveIntents — multiple intents preserved in order', async t => {
+    t.same(resolveIntents(['dev', 'debug']), ['dev', 'debug']);
+});

package/src/runServer.ts

@@ -4,15 +4,21 @@ import {basename, resolve} from 'node:path';
 import {analyzeFolder, synthesizeServerFromHandlers} from './folderAnalysis.ts';
 import load from './loadServer.ts';
 
+/** Default intents applied when none are provided on the CLI. */
+export const DEFAULT_INTENTS = ['microservice', 'integration', 'dev'] as const;
+
 /**
  * Runs the standard platform lifecycle: start → test → (CI) stop.
+ *
+ * @param intents - Active intents that control which config blocks and layers are activated.
+ *   Defaults to {@link DEFAULT_INTENTS} when omitted.
  */
-export async function runPlatform(serverDef: SolutionFactory, name: string): Promise<void> {
-    const platform = await load(serverDef as unknown as Parameters<typeof load>[0], name, name, [
-        'microservice',
-        'integration',
-        'dev',
-    ]);
+export async function runPlatform(
+    serverDef: SolutionFactory,
+    name: string,
+    intents: string[] = [...DEFAULT_INTENTS],
+): Promise<void> {
+    const platform = await load(serverDef as unknown as Parameters<typeof load>[0], name, name, intents);
     await platform.start!({});
     await platform.test!(undefined);
     if (process.env.CI) await platform.stop!();
@@ -28,9 +34,19 @@ export async function runPlatform(serverDef: SolutionFactory, name: string): Pro
  *   4. `server.ts` alone — server-only suite or realm.
  *   5. Folder contains handler files — synthesize a server suite on the fly.
  *   6. Throws if nothing matched.
+ *
+ * @param options.intents - Active intents from the CLI (positional args after the optional target
+ *   path). When empty, {@link DEFAULT_INTENTS} are used so that a plain `blong` invocation works
+ *   out of the box.
  */
-export async function autoRun(options: {cwd: string; target?: string}): Promise<void> {
-    const {cwd, target} = options;
+export async function autoRun(options: {
+    cwd: string;
+    target?: string;
+    intents?: string[];
+}): Promise<void> {
+    const {cwd, target, intents: cliIntents} = options;
+    // Use CLI-supplied intents; fall back to defaults when the user passed none.
+    const intents = cliIntents && cliIntents.length > 0 ? cliIntents : [...DEFAULT_INTENTS];
 
     if (target && existsSync(target)) {
         (await import(target)).default(load);
@@ -48,19 +64,19 @@ export async function autoRun(options: {cwd: string; target?: string}): Promise<
         const {default: serverDef} = await import(serverFile);
         const {default: browserDef} = await import(browserFile);
         const platforms: Awaited<ReturnType<typeof load>>[] = await Promise.all([
-            load(serverDef, name, name, ['microservice', 'integration', 'dev']),
-            load(browserDef, name, name, ['microservice', 'integration', 'dev']),
+            load(serverDef, name, name, intents),
+            load(browserDef, name, name, intents),
         ]);
         for (const platform of platforms) await platform.start({});
         await platforms[1].test!(undefined);
         if (process.env.CI) for (const platform of platforms) await platform.stop();
     } else if (existsSync(serverFile)) {
         const {default: serverDef} = await import(serverFile);
-        await runPlatform(serverDef, name);
+        await runPlatform(serverDef, name, intents);
     } else {
         const analysis = await analyzeFolder(cwd);
         if (analysis.kind === 'handlers' || analysis.kind === 'mixed') {
-            await runPlatform(await synthesizeServerFromHandlers(cwd, analysis), name);
+            await runPlatform(await synthesizeServerFromHandlers(cwd, analysis), name, intents);
         } else {
             throw new Error(
                 `No entry point found in ${cwd}. ` +