@feasibleone/blong-gogo 1.21.0 → 1.23.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [1.23.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.22.0...blong-gogo-v1.23.0) (2026-05-14)
+
+
+### Features
+
+* expected errors ([57ab05e](https://github.com/feasibleone/blong/commit/57ab05ed66b86405561f519e395e30f43b4fffa2))
+
+## [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.23.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/AdapterBase.ts

@@ -14,6 +14,7 @@ import PQueue from 'p-queue';
 import merge from 'ut-function.merge';
 
 import ConfigRuntime from './ConfigRuntime.ts';
+import {isExpectedError} from './lib.ts';
 import loop from './loop.ts';
 
 const errorMap: IErrorMap = {
@@ -177,11 +178,12 @@ export class AdapterBase<T, C extends IContext> implements AdapterHandlerContext
     }
 
     error(error: ITypedError, $meta: IMeta): void {
-        if ((this.log as {error?: (...args: unknown[]) => void})?.error) {
-            if (error.type && $meta?.expect?.includes?.(error.type)) return;
-            if ($meta) error.method = $meta.method;
-            (this.log as {error: (...args: unknown[]) => void}).error(error);
+        if ($meta) error.method = $meta.method;
+        if (isExpectedError(error.type, $meta?.expect)) {
+            (this.log as {debug?: (...args: unknown[]) => void})?.debug?.(error);
+            return;
         }
+        (this.log as {error?: (...args: unknown[]) => void})?.error?.(error);
     }
 
     findValidation(): unknown {

package/src/Gateway.ts

@@ -20,7 +20,7 @@ import {v4} from 'uuid';
 import type {IResolution} from './Resolution.ts';
 import type {IRpcClient} from './RpcClient.ts';
 import jwt from './jwt.ts';
-import {methodParts, snakeToCamel} from './lib.ts';
+import {isExpectedError, methodParts, snakeToCamel} from './lib.ts';
 import type {IConfig as IConfigMLE} from './mle.ts';
 import swagger from './swagger.ts';
 
@@ -60,6 +60,15 @@ interface IConfig extends IConfigMLE {
     logLevel?: LevelWithSilent;
     cors?: unknown;
     debug?: boolean;
+    /**
+     * When true, the gateway accepts the `expect` field from JSON-RPC request
+     * bodies and uses it to suppress error-level log entries for declared
+     * expected errors (demoting them to `debug` level).
+     *
+     * Set to `true` in the `dev` intent.  Must be `false` (the default) in
+     * production to prevent callers from suppressing audit-level error logs.
+     */
+    expectedErrors?: boolean;
     errorFields: unknown[];
     jwt: {
         cache: object;
@@ -147,6 +156,7 @@ export default class Gateway extends Internal implements IGateway {
             encrypt: undefined,
         },
         debug: false,
+        expectedErrors: false,
         errorFields: [],
         jwt: {
             cache: {},
@@ -418,6 +428,13 @@ export default class Gateway extends Internal implements IGateway {
                                   timeout: false,
                                   expect: undefined,
                               };
+                    // Only honour `expect` from the request body when the gateway
+                    // is configured to allow it.  This prevents external callers
+                    // from suppressing error-level logs in production.
+                    const resolvedExpect =
+                        this.#config.expectedErrors && expect
+                            ? ([] as string[]).concat(expect)
+                            : undefined;
                     const methodName = isWildcard
                         ? new URL(request.url, 'http://localhost').pathname
                               .slice(5)
@@ -432,7 +449,7 @@ export default class Gateway extends Internal implements IGateway {
                             ...(timeout && {
                                 timeout: this.#platform.timing.after(timeout as number),
                             }),
-                            ...(expect && {expect: ([] as string[]).concat(expect)}),
+                            ...(resolvedExpect && {expect: resolvedExpect}),
                             ...this._meta(request, pkg?.version, methodName.split('.')[0]),
                         };
                         const notfound = (): unknown =>
@@ -483,10 +500,17 @@ export default class Gateway extends Internal implements IGateway {
                             httpResponse?: unknown;
                             [key: string]: unknown;
                         };
-                        request.log.error(
-                            {err: error, method: methodName},
-                            'gateway handler error',
-                        );
+                        if (isExpectedError(typedError.type as string | undefined, resolvedExpect)) {
+                            request.log.debug(
+                                {err: error, method: methodName},
+                                'gateway expected error',
+                            );
+                        } else {
+                            request.log.error(
+                                {err: error, method: methodName},
+                                'gateway handler error',
+                            );
+                        }
                         this._applyMeta(
                             reply
                                 .header('x-envoy-decorator-operation', methodName)

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/expected-errors.test.ts

@@ -0,0 +1,291 @@
+/**
+ * Unit tests for the "expected errors" feature.
+ *
+ * Covers:
+ *  - isExpectedError() matching rules (exact, array, wildcard)
+ *  - AdapterBase.error() log-level demotion for expected errors
+ *  - Gateway respects `expectedErrors` config flag
+ *  - Propagation: expect travels with $meta through the handler chain
+ */
+
+import assert from 'node:assert';
+import {describe, it} from 'node:test';
+
+import {isExpectedError} from './lib.ts';
+
+// ---------------------------------------------------------------------------
+// isExpectedError() — matching rules
+// ---------------------------------------------------------------------------
+
+describe('isExpectedError — matching rules', () => {
+    it('returns false when error type is undefined', () => {
+        assert.strictEqual(isExpectedError(undefined, 'foo.bar'), false);
+    });
+
+    it('returns false when expect is undefined', () => {
+        assert.strictEqual(isExpectedError('foo.bar', undefined), false);
+    });
+
+    it('returns false when expect is an empty array', () => {
+        assert.strictEqual(isExpectedError('foo.bar', []), false);
+    });
+
+    it('exact string — matches identical type', () => {
+        assert.strictEqual(isExpectedError('parking.invalidZone', 'parking.invalidZone'), true);
+    });
+
+    it('exact string — does not match different type', () => {
+        assert.strictEqual(isExpectedError('parking.rateLimit', 'parking.invalidZone'), false);
+    });
+
+    it('array — matches when type is in the list', () => {
+        assert.strictEqual(
+            isExpectedError('auth.unauthorized', ['parking.invalidZone', 'auth.unauthorized']),
+            true,
+        );
+    });
+
+    it('array — does not match when type is absent from the list', () => {
+        assert.strictEqual(
+            isExpectedError('payment.failed', ['parking.invalidZone', 'auth.unauthorized']),
+            false,
+        );
+    });
+
+    it('wildcard — matches any type with the given prefix', () => {
+        assert.strictEqual(isExpectedError('parking.invalidZone', 'parking.*'), true);
+        assert.strictEqual(isExpectedError('parking.rateLimit', 'parking.*'), true);
+    });
+
+    it('wildcard — does not match a different namespace', () => {
+        assert.strictEqual(isExpectedError('auth.unauthorized', 'parking.*'), false);
+    });
+
+    it('wildcard — does not match the prefix segment itself (no dot)', () => {
+        // 'parking' alone should NOT match 'parking.*' (requires the dot)
+        assert.strictEqual(isExpectedError('parking', 'parking.*'), false);
+    });
+
+    it('array with wildcard — matches when a wildcard entry covers the type', () => {
+        assert.strictEqual(
+            isExpectedError('parking.invalidZone', ['auth.*', 'parking.*']),
+            true,
+        );
+    });
+
+    it('wildcard at top of namespace — auth.*', () => {
+        assert.strictEqual(isExpectedError('auth.unauthorized', 'auth.*'), true);
+        assert.strictEqual(isExpectedError('auth.tokenExpired', 'auth.*'), true);
+        assert.strictEqual(isExpectedError('gateway.jwtMissingHeader', 'auth.*'), false);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// AdapterBase.error() — log-level demotion
+// ---------------------------------------------------------------------------
+
+describe('AdapterBase.error() — log-level demotion', () => {
+    /**
+     * Minimal stand-in for AdapterBase that exposes only the `error()` method
+     * under test.  We copy the implementation verbatim so we are testing the
+     * real logic without spinning up a full adapter.
+     */
+    function makeAdapter(log: Record<string, (...a: unknown[]) => void>) {
+        return {
+            log,
+            error(
+                error: {type?: string; method?: string},
+                $meta: {method?: string; expect?: string | string[]},
+            ) {
+                if ($meta) error.method = $meta.method;
+                if (isExpectedError(error.type, $meta?.expect)) {
+                    (this.log as Record<string, (...a: unknown[]) => void>).debug?.(error);
+                    return;
+                }
+                (this.log as Record<string, (...a: unknown[]) => void>).error?.(error);
+            },
+        };
+    }
+
+    it('logs at error level when expect is not set', () => {
+        const logged: {level: string; error: unknown}[] = [];
+        const adapter = makeAdapter({
+            error: e => logged.push({level: 'error', error: e}),
+            debug: e => logged.push({level: 'debug', error: e}),
+        });
+
+        adapter.error({type: 'parking.invalidZone'}, {method: 'parkingTest'});
+
+        assert.strictEqual(logged.length, 1);
+        assert.strictEqual(logged[0].level, 'error');
+    });
+
+    it('logs at debug level and does not log at error when error is expected', () => {
+        const logged: {level: string; error: unknown}[] = [];
+        const adapter = makeAdapter({
+            error: e => logged.push({level: 'error', error: e}),
+            debug: e => logged.push({level: 'debug', error: e}),
+        });
+
+        adapter.error(
+            {type: 'parking.invalidZone'},
+            {method: 'parkingTest', expect: 'parking.invalidZone'},
+        );
+
+        assert.strictEqual(logged.length, 1);
+        assert.strictEqual(logged[0].level, 'debug');
+    });
+
+    it('logs at debug level for wildcard match', () => {
+        const logged: {level: string; error: unknown}[] = [];
+        const adapter = makeAdapter({
+            error: e => logged.push({level: 'error', error: e}),
+            debug: e => logged.push({level: 'debug', error: e}),
+        });
+
+        adapter.error(
+            {type: 'parking.rateLimit'},
+            {method: 'parkingTest', expect: 'parking.*'},
+        );
+
+        assert.strictEqual(logged.length, 1);
+        assert.strictEqual(logged[0].level, 'debug');
+    });
+
+    it('logs at error level when the error type does not match expect', () => {
+        const logged: {level: string; error: unknown}[] = [];
+        const adapter = makeAdapter({
+            error: e => logged.push({level: 'error', error: e}),
+            debug: e => logged.push({level: 'debug', error: e}),
+        });
+
+        adapter.error(
+            {type: 'auth.unauthorized'},
+            {method: 'someMethod', expect: 'parking.invalidZone'},
+        );
+
+        assert.strictEqual(logged.length, 1);
+        assert.strictEqual(logged[0].level, 'error');
+    });
+
+    it('attaches $meta.method to the error object', () => {
+        const captured: unknown[] = [];
+        const adapter = makeAdapter({
+            error: e => captured.push(e),
+            debug: () => {},
+        });
+
+        const err: {type: string; method?: string} = {type: 'foo.bar'};
+        adapter.error(err, {method: 'someMethod'});
+
+        assert.strictEqual((captured[0] as typeof err).method, 'someMethod');
+    });
+
+    it('attaches $meta.method even when the error is expected', () => {
+        const captured: unknown[] = [];
+        const adapter = makeAdapter({
+            error: () => {},
+            debug: e => captured.push(e),
+        });
+
+        const err: {type: string; method?: string} = {type: 'parking.invalidZone'};
+        adapter.error(err, {method: 'parkingTest', expect: 'parking.invalidZone'});
+
+        assert.strictEqual((captured[0] as typeof err).method, 'parkingTest');
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Gateway expectedErrors flag
+// ---------------------------------------------------------------------------
+
+describe('Gateway — expectedErrors config flag', () => {
+    /**
+     * Simulate the gateway route-handler logic that builds `resolvedExpect`.
+     * Returns the value of `resolvedExpect` that the gateway would compute.
+     */
+    function buildResolvedExpect(
+        expectedErrorsEnabled: boolean,
+        expectFromBody: string | string[] | undefined,
+    ): string[] | undefined {
+        return expectedErrorsEnabled && expectFromBody
+            ? ([] as string[]).concat(expectFromBody)
+            : undefined;
+    }
+
+    it('resolves expect when expectedErrors is true and expect is provided', () => {
+        const result = buildResolvedExpect(true, 'parking.invalidZone');
+        assert.deepStrictEqual(result, ['parking.invalidZone']);
+    });
+
+    it('resolves expect array when expectedErrors is true', () => {
+        const result = buildResolvedExpect(true, ['parking.invalidZone', 'auth.unauthorized']);
+        assert.deepStrictEqual(result, ['parking.invalidZone', 'auth.unauthorized']);
+    });
+
+    it('returns undefined when expectedErrors is false (production)', () => {
+        const result = buildResolvedExpect(false, 'parking.invalidZone');
+        assert.strictEqual(result, undefined);
+    });
+
+    it('returns undefined when expect is not provided even if expectedErrors is true', () => {
+        const result = buildResolvedExpect(true, undefined);
+        assert.strictEqual(result, undefined);
+    });
+
+    it('with resolvedExpect=undefined, isExpectedError always returns false', () => {
+        assert.strictEqual(isExpectedError('parking.invalidZone', undefined), false);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Meta propagation — $meta.expect travels through handler chain
+// ---------------------------------------------------------------------------
+
+describe('$meta.expect propagation', () => {
+    /**
+     * Simulate a two-hop dispatch: caller → first handler → second handler.
+     * The second handler logs an error and the first handler propagates it.
+     * Verify that $meta.expect set by the caller controls log level at every hop.
+     */
+    it('expect set by caller controls log level at every handler in the chain', () => {
+        const logged: {level: string; type: string}[] = [];
+
+        function logError(error: {type: string}, $meta: {expect?: string | string[]}) {
+            if (isExpectedError(error.type, $meta?.expect)) {
+                logged.push({level: 'debug', type: error.type});
+            } else {
+                logged.push({level: 'error', type: error.type});
+            }
+        }
+
+        const callerMeta = {method: 'callerMethod', expect: 'foo.someError'};
+
+        // Simulate two handler hops both receiving the same $meta
+        logError({type: 'foo.someError'}, callerMeta); // hop 1
+        logError({type: 'foo.someError'}, callerMeta); // hop 2
+
+        assert.strictEqual(logged.length, 2);
+        assert.ok(logged.every(l => l.level === 'debug'), 'all hops should log at debug');
+    });
+
+    it('an error type not in expect is still logged at error level on all hops', () => {
+        const logged: {level: string; type: string}[] = [];
+
+        function logError(error: {type: string}, $meta: {expect?: string | string[]}) {
+            if (isExpectedError(error.type, $meta?.expect)) {
+                logged.push({level: 'debug', type: error.type});
+            } else {
+                logged.push({level: 'error', type: error.type});
+            }
+        }
+
+        const callerMeta = {method: 'callerMethod', expect: 'foo.someError'};
+
+        logError({type: 'bar.otherError'}, callerMeta); // unexpected on hop 1
+        logError({type: 'bar.otherError'}, callerMeta); // unexpected on hop 2
+
+        assert.strictEqual(logged.length, 2);
+        assert.ok(logged.every(l => l.level === 'error'), 'unexpected errors stay at error level');
+    });
+});

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/lib.ts

@@ -66,6 +66,28 @@ export function parseAnnotatedKey(key: string): {
     return {annotations, handlerName};
 }
 
+/**
+ * Returns true when an error type matches the `expect` declaration on `$meta`.
+ *
+ * Matching rules:
+ *  - Exact string: `'foo.bar'` matches only `foo.bar`
+ *  - Array of strings: any element that matches (exact or wildcard)
+ *  - Wildcard prefix: `'foo.*'` matches any type starting with `foo.`
+ */
+export function isExpectedError(
+    errorType: string | undefined,
+    expect: string | string[] | undefined,
+): boolean {
+    if (!errorType || !expect) return false;
+    const patterns = ([] as string[]).concat(expect);
+    return patterns.some(pattern => {
+        if (pattern.endsWith('.*')) {
+            return errorType.startsWith(pattern.slice(0, -1));
+        }
+        return errorType === pattern;
+    });
+}
+
 let loginCache: Promise<{protocol: string; hostname: string; port: number}> | null = null;
 export async function loginService(
     discovery: (service: string) => Promise<{protocol: string; hostname: string; port: number}>,

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}. ` +