@elaraai/e3-cli 0.0.2-beta.8 → 1.0.0

package/dist/src/path-resolver.spec.js

@@ -0,0 +1,247 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Tests for the dataset path resolver.
+ *
+ * The pure functions (`levenshtein`, `suggestSimilar`, `indexFromTree`,
+ * `indexFromRemoteEntries`, `resolveDatasetPathFromIndex`) are exercised
+ * directly without a real repository.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { variant } from '@elaraai/east';
+import { levenshtein, suggestSimilar, indexFromTree, indexFromRemoteEntries, resolveDatasetPathFromIndex, } from './path-resolver.js';
+// =============================================================================
+// Tree fixture builders
+// =============================================================================
+function leaf(name) {
+    return { name, kind: 'dataset' };
+}
+function branch(name, children) {
+    return { name, kind: 'tree', children };
+}
+function inputs(...names) {
+    return branch('inputs', names.map(leaf));
+}
+function tasks(...names) {
+    return branch('tasks', names.map(leaf));
+}
+// Remote ListEntry builders
+function remoteDataset(path) {
+    return variant('dataset', {
+        path,
+        type: variant('String', null),
+        hash: variant('none', null),
+        size: variant('none', null),
+    });
+}
+function remoteTree(path) {
+    return variant('tree', { path, kind: variant('struct', null) });
+}
+// =============================================================================
+// levenshtein
+// =============================================================================
+describe('levenshtein', () => {
+    it('returns 0 for identical strings', () => {
+        assert.strictEqual(levenshtein('abc', 'abc'), 0);
+        assert.strictEqual(levenshtein('', ''), 0);
+    });
+    it('returns length of the non-empty string when one side is empty', () => {
+        assert.strictEqual(levenshtein('', 'abc'), 3);
+        assert.strictEqual(levenshtein('xyz', ''), 3);
+    });
+    it('returns 1 for single insertion', () => {
+        assert.strictEqual(levenshtein('abc', 'abcd'), 1);
+    });
+    it('returns 1 for single deletion', () => {
+        assert.strictEqual(levenshtein('abcd', 'abc'), 1);
+    });
+    it('returns 1 for single substitution', () => {
+        assert.strictEqual(levenshtein('abc', 'abd'), 1);
+    });
+    it('handles the classic kitten/sitting case', () => {
+        assert.strictEqual(levenshtein('kitten', 'sitting'), 3);
+    });
+    it('handles unicode characters as JS code units', () => {
+        // résumé vs resume — two characters with accents replaced
+        assert.strictEqual(levenshtein('résumé', 'resume'), 2);
+    });
+});
+// =============================================================================
+// suggestSimilar
+// =============================================================================
+describe('suggestSimilar', () => {
+    it('returns exact match first', () => {
+        const result = suggestSimilar('greet', ['greeting', 'greet', 'grit'], 5);
+        assert.strictEqual(result[0], 'greet');
+    });
+    it('returns single-char typos within threshold', () => {
+        const result = suggestSimilar('greet', ['greeting', 'gret', 'shout'], 5);
+        assert.ok(result.includes('gret'));
+    });
+    it('filters out candidates beyond the threshold', () => {
+        // target length 5 → threshold = max(2, 2) = 2
+        const result = suggestSimilar('greet', ['completely-unrelated', 'gret'], 5);
+        assert.deepStrictEqual(result, ['gret']);
+    });
+    it('returns at most `max` candidates', () => {
+        const result = suggestSimilar('a', ['a', 'b', 'c', 'd', 'e', 'f'], 3);
+        assert.strictEqual(result.length, 3);
+    });
+    it('returns candidates in distance order', () => {
+        const result = suggestSimilar('hello', ['hellp', 'hxllo', 'help'], 5);
+        // hellp d=1, hxllo d=1, help d=2 (all within threshold)
+        // First two could be in either order (both d=1), but help must come last
+        assert.strictEqual(result[result.length - 1], 'help');
+    });
+    it('returns empty array when candidates is empty', () => {
+        assert.deepStrictEqual(suggestSimilar('greet', [], 5), []);
+    });
+    it('still applies threshold of 2 for very short targets', () => {
+        // target 'a' → threshold = max(2, 0) = 2
+        const result = suggestSimilar('a', ['ab', 'abc', 'abcd'], 5);
+        // ab d=1, abc d=2, abcd d=3 (excluded)
+        assert.ok(result.includes('ab'));
+        assert.ok(result.includes('abc'));
+        assert.ok(!result.includes('abcd'));
+    });
+    it('handles very long names with appropriate threshold', () => {
+        // target length 100 → threshold = 50; far-apart strings still excluded
+        const longName = 'a'.repeat(100);
+        const result = suggestSimilar(longName, ['b'.repeat(100)], 5);
+        // 100 edits — far above threshold of 50
+        assert.deepStrictEqual(result, []);
+    });
+});
+// =============================================================================
+// indexFromTree
+// =============================================================================
+describe('indexFromTree', () => {
+    it('returns [] for empty tree', () => {
+        assert.deepStrictEqual(indexFromTree([]), []);
+    });
+    it('indexes inputs as kind=input with [inputs, name] storage', () => {
+        const tree = [inputs('name', 'count')];
+        const result = indexFromTree(tree);
+        const name = result.find((e) => e.name === 'name');
+        assert.strictEqual(name.kind, 'input');
+        assert.deepStrictEqual(name.storage.map((s) => s.value), ['inputs', 'name']);
+    });
+    it('indexes tasks as kind=task-output with [tasks, name, output] storage', () => {
+        const tree = [tasks('greet')];
+        const result = indexFromTree(tree);
+        const greet = result.find((e) => e.name === 'greet');
+        assert.strictEqual(greet.kind, 'task-output');
+        assert.deepStrictEqual(greet.storage.map((s) => s.value), ['tasks', 'greet', 'output']);
+    });
+    it('indexes both inputs and tasks in a typical workspace', () => {
+        const tree = [inputs('name'), tasks('greet', 'shout')];
+        const result = indexFromTree(tree);
+        assert.strictEqual(result.length, 3);
+        assert.ok(result.some((e) => e.name === 'name' && e.kind === 'input'));
+        assert.ok(result.some((e) => e.name === 'greet' && e.kind === 'task-output'));
+        assert.ok(result.some((e) => e.name === 'shout' && e.kind === 'task-output'));
+    });
+    it('treats nested non-input/non-task branches as kind=other with dotted name', () => {
+        const tree = [branch('config', [leaf('value')])];
+        const result = indexFromTree(tree);
+        assert.strictEqual(result.length, 1);
+        const e = result[0];
+        assert.strictEqual(e.kind, 'other');
+        assert.strictEqual(e.name, 'config.value');
+        assert.deepStrictEqual(e.storage.map((s) => s.value), ['config', 'value']);
+    });
+    it('handles a leaf at the root (no prefix)', () => {
+        // unusual but well-defined: dataset at root would be kind=other with bare name
+        const tree = [leaf('bare')];
+        const result = indexFromTree(tree);
+        assert.strictEqual(result.length, 1);
+        assert.strictEqual(result[0].kind, 'other');
+        assert.strictEqual(result[0].name, 'bare');
+    });
+});
+// =============================================================================
+// indexFromRemoteEntries
+// =============================================================================
+describe('indexFromRemoteEntries', () => {
+    it('returns [] for empty list', () => {
+        assert.deepStrictEqual(indexFromRemoteEntries([]), []);
+    });
+    it('indexes inputs.<name> as kind=input', () => {
+        const result = indexFromRemoteEntries([remoteDataset('inputs.name')]);
+        assert.strictEqual(result.length, 1);
+        assert.strictEqual(result[0].kind, 'input');
+        assert.strictEqual(result[0].name, 'name');
+    });
+    it('indexes tasks.<name> as kind=task-output with output suffix in storage', () => {
+        const result = indexFromRemoteEntries([remoteDataset('tasks.greet')]);
+        assert.strictEqual(result.length, 1);
+        assert.strictEqual(result[0].kind, 'task-output');
+        assert.strictEqual(result[0].name, 'greet');
+        assert.deepStrictEqual(result[0].storage.map((s) => s.value), ['tasks', 'greet', 'output']);
+    });
+    it('ignores tree entries (only datasets are indexable leaves)', () => {
+        const result = indexFromRemoteEntries([remoteTree('inputs'), remoteDataset('inputs.name')]);
+        assert.strictEqual(result.length, 1);
+        assert.strictEqual(result[0].name, 'name');
+    });
+});
+// =============================================================================
+// resolveDatasetPathFromIndex
+// =============================================================================
+describe('resolveDatasetPathFromIndex', () => {
+    const index = indexFromTree([
+        inputs('name', 'count'),
+        tasks('greet', 'shout'),
+    ]);
+    it('resolves a known input', () => {
+        const result = resolveDatasetPathFromIndex('dev.name', index);
+        assert.strictEqual(result.ws, 'dev');
+        assert.strictEqual(result.kind, 'input');
+        assert.deepStrictEqual(result.path.map((s) => s.value), ['inputs', 'name']);
+    });
+    it('resolves a known task with the output suffix added', () => {
+        const result = resolveDatasetPathFromIndex('dev.greet', index);
+        assert.strictEqual(result.kind, 'task-output');
+        assert.deepStrictEqual(result.path.map((s) => s.value), ['tasks', 'greet', 'output']);
+    });
+    it('errors on path with no name segment', () => {
+        assert.throws(() => resolveDatasetPathFromIndex('dev', index), /Path must include a name/);
+    });
+    it('rejects legacy inputs.<name> form with a hint', () => {
+        assert.throws(() => resolveDatasetPathFromIndex('dev.inputs.name', index), /Use the short form: 'dev.name'/);
+    });
+    it('rejects legacy tasks.<name>.output form with a hint', () => {
+        assert.throws(() => resolveDatasetPathFromIndex('dev.tasks.greet.output', index), /Use the short form: 'dev.greet'/);
+    });
+    it('suggests close matches for typos', () => {
+        assert.throws(() => resolveDatasetPathFromIndex('dev.gret', index), /Did you mean.*dev\.greet/s);
+    });
+    it('lists available names when no close match exists', () => {
+        assert.throws(() => resolveDatasetPathFromIndex('dev.completelyDifferentName', index), /Available names/);
+    });
+    it('caps the available list at 10 names with a "... and N more" suffix', () => {
+        const many = indexFromTree([
+            inputs(...Array.from({ length: 15 }, (_, i) => `in${i}`)),
+        ]);
+        let err;
+        try {
+            resolveDatasetPathFromIndex('dev.completelyDifferentName', many);
+        }
+        catch (e) {
+            err = e;
+        }
+        assert.ok(err, 'expected error');
+        assert.match(err.message, /\.\.\. and 5 more/);
+    });
+    it('reports ambiguity when an input and task share a name', () => {
+        const ambig = indexFromTree([inputs('foo'), tasks('foo')]);
+        assert.throws(() => resolveDatasetPathFromIndex('dev.foo', ambig), /ambiguous/);
+    });
+    it('rejects nested field access past the leaf', () => {
+        assert.throws(() => resolveDatasetPathFromIndex('dev.greet.field', index), /Nested field access/);
+    });
+});
+//# sourceMappingURL=path-resolver.spec.js.map

package/dist/src/path-resolver.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-resolver.spec.js","sourceRoot":"","sources":["../../src/path-resolver.spec.ts"],"names":[],"mappings":"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"}

package/dist/src/utils.d.ts

@@ -2,8 +2,72 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Licensed under BSL 1.1. See LICENSE for details.
  */
+/** Character width used when truncating object hashes for display. */
+export declare const HASH_DISPLAY_WIDTH = 12;
+/** Truncate a hash to `HASH_DISPLAY_WIDTH` chars with a trailing ellipsis. */
+export declare function shortHash(hash: string): string;
 import { parseDatasetPath, parsePackageRef } from '@elaraai/e3-types';
+/**
+ * Resolve the `<repo>` positional argument with fallback to `E3_REPO` env var
+ * then `.` (cwd). Used by every command that accepts a repository argument so
+ * users in a current directory can drop the leading `.`.
+ */
+export declare function defaultRepoArg(arg: string | undefined): string;
+/**
+ * Wrap a command handler whose first parameter is `<repo>` so that the
+ * Commander action callback can pass `string | undefined` and the handler
+ * still sees a fully-resolved repo string.
+ */
+export declare function withDefaultRepo<A extends unknown[]>(handler: (repo: string, ...args: A) => void | Promise<void>): (repo: string | undefined, ...args: A) => void | Promise<void>;
 export { parseDatasetPath, parsePackageRef };
+/**
+ * Repository location - either local filesystem or remote URL.
+ */
+export type RepoLocation = {
+    type: 'local';
+    path: string;
+} | {
+    type: 'remote';
+    baseUrl: string;
+    repo: string;
+    token: string;
+};
+/**
+ * Parse a repository location argument.
+ *
+ * Supports:
+ * - Local paths: `.`, `./repo`, `/path/to/repo`
+ * - Remote URLs: `http://...`, `https://...`
+ *
+ * For remote URLs, the URL should be the user-facing "shareable" URL,
+ * e.g., `https://platform.example.com/repos/my_repo`.
+ * The CLI will internally add `/api` when making API calls.
+ *
+ * For remote locations, this function will load and validate the auth token.
+ * If not logged in or token is expired and cannot be refreshed, throws an error.
+ *
+ * @returns For local: { type: 'local', path: '/absolute/path/to/repo' }
+ *          For remote: { type: 'remote', baseUrl: 'https://example.com', repo: 'my_repo', token: '...' }
+ */
+export declare function parseRepoLocation(arg: string): Promise<RepoLocation>;
+/**
+ * Repository location without required token (for sync parsing).
+ */
+export type RepoLocationNoToken = {
+    type: 'local';
+    path: string;
+} | {
+    type: 'remote';
+    baseUrl: string;
+    repo: string;
+};
+/**
+ * Parse a repository location (synchronous, no auth).
+ *
+ * Use this only for operations that don't need authentication (e.g., local repos).
+ * For remote repos, use parseRepoLocation() instead.
+ */
+export declare function parseRepoLocationSync(arg: string): RepoLocationNoToken;
 /**
  * Resolve repository path from CLI argument.
  * Supports `.` for current directory and relative/absolute paths.
@@ -18,7 +82,18 @@ export declare function parsePackageSpec(spec: string): {
     version: string;
 };
 /**
- * Format error for CLI output.
+ * Format an error into a human-readable CLI message.
+ *
+ * Handles three error categories:
+ * - {@link ApiError} — humanizes the error code (e.g. `"package_not_found"` → `"Package not found"`)
+ *   and appends details if present (string details verbatim, objects as JSON).
+ * - Standard `Error` — returns `.message`.
+ * - Other values — coerces to string via `String()`.
+ *
+ * The returned string is intended for `exitError()` which prefixes it with `"Error: "`.
+ *
+ * @param err - The caught error value (may be any type)
+ * @returns A single-line, human-readable error description
  */
 export declare function formatError(err: unknown): string;
 /**

package/dist/src/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAE7C;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAGhF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAKhD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAGhD"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAGD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAItE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAG9D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,OAAO,EAAE,EACjD,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAEnD,MAAM,MAAM,GAAG,SAAS,EAAE,GAAG,MAAM,CAAC,0BAC7C;AAGD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAqB1E;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CActE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAGhF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAchD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAGhD"}

package/dist/src/utils.js

@@ -6,10 +6,93 @@
  * CLI utilities for path parsing and resolution
  */
 import { resolve } from 'path';
+/** Character width used when truncating object hashes for display. */
+export const HASH_DISPLAY_WIDTH = 12;
+/** Truncate a hash to `HASH_DISPLAY_WIDTH` chars with a trailing ellipsis. */
+export function shortHash(hash) {
+    return `${hash.slice(0, HASH_DISPLAY_WIDTH)}...`;
+}
 import { repoGet } from '@elaraai/e3-core';
 import { parseDatasetPath, parsePackageRef } from '@elaraai/e3-types';
+import { ApiError } from '@elaraai/e3-api-client';
+import { getValidToken } from './credentials.js';
+/**
+ * Resolve the `<repo>` positional argument with fallback to `E3_REPO` env var
+ * then `.` (cwd). Used by every command that accepts a repository argument so
+ * users in a current directory can drop the leading `.`.
+ */
+export function defaultRepoArg(arg) {
+    if (arg && arg.length > 0)
+        return arg;
+    return process.env.E3_REPO ?? '.';
+}
+/**
+ * Wrap a command handler whose first parameter is `<repo>` so that the
+ * Commander action callback can pass `string | undefined` and the handler
+ * still sees a fully-resolved repo string.
+ */
+export function withDefaultRepo(handler) {
+    return (repo, ...args) => handler(defaultRepoArg(repo), ...args);
+}
 // Re-export for convenience
 export { parseDatasetPath, parsePackageRef };
+/**
+ * Parse a repository location argument.
+ *
+ * Supports:
+ * - Local paths: `.`, `./repo`, `/path/to/repo`
+ * - Remote URLs: `http://...`, `https://...`
+ *
+ * For remote URLs, the URL should be the user-facing "shareable" URL,
+ * e.g., `https://platform.example.com/repos/my_repo`.
+ * The CLI will internally add `/api` when making API calls.
+ *
+ * For remote locations, this function will load and validate the auth token.
+ * If not logged in or token is expired and cannot be refreshed, throws an error.
+ *
+ * @returns For local: { type: 'local', path: '/absolute/path/to/repo' }
+ *          For remote: { type: 'remote', baseUrl: 'https://example.com', repo: 'my_repo', token: '...' }
+ */
+export async function parseRepoLocation(arg) {
+    if (arg.startsWith('https://') || arg.startsWith('http://')) {
+        const url = new URL(arg);
+        // Extract repo name from path: /repos/{repo}[/...]
+        const match = url.pathname.match(/^\/repos\/([^/]+)/);
+        if (!match) {
+            throw new Error(`Invalid remote URL: expected /repos/{repo} in path, got ${url.pathname}`);
+        }
+        // Load and validate token
+        const token = await getValidToken(url.origin);
+        return {
+            type: 'remote',
+            baseUrl: url.origin,
+            repo: match[1],
+            token,
+        };
+    }
+    return { type: 'local', path: resolveRepo(arg) };
+}
+/**
+ * Parse a repository location (synchronous, no auth).
+ *
+ * Use this only for operations that don't need authentication (e.g., local repos).
+ * For remote repos, use parseRepoLocation() instead.
+ */
+export function parseRepoLocationSync(arg) {
+    if (arg.startsWith('https://') || arg.startsWith('http://')) {
+        const url = new URL(arg);
+        const match = url.pathname.match(/^\/repos\/([^/]+)/);
+        if (!match) {
+            throw new Error(`Invalid remote URL: expected /repos/{repo} in path, got ${url.pathname}`);
+        }
+        return {
+            type: 'remote',
+            baseUrl: url.origin,
+            repo: match[1],
+        };
+    }
+    return { type: 'local', path: resolveRepo(arg) };
+}
 /**
  * Resolve repository path from CLI argument.
  * Supports `.` for current directory and relative/absolute paths.
@@ -27,9 +110,29 @@ export function parsePackageSpec(spec) {
     return { name, version: version ?? 'latest' };
 }
 /**
- * Format error for CLI output.
+ * Format an error into a human-readable CLI message.
+ *
+ * Handles three error categories:
+ * - {@link ApiError} — humanizes the error code (e.g. `"package_not_found"` → `"Package not found"`)
+ *   and appends details if present (string details verbatim, objects as JSON).
+ * - Standard `Error` — returns `.message`.
+ * - Other values — coerces to string via `String()`.
+ *
+ * The returned string is intended for `exitError()` which prefixes it with `"Error: "`.
+ *
+ * @param err - The caught error value (may be any type)
+ * @returns A single-line, human-readable error description
  */
 export function formatError(err) {
+    if (err instanceof ApiError) {
+        // Humanize the error code: "execution_not_found" → "Execution not found"
+        const message = err.code.replace(/_/g, ' ').replace(/^\w/, c => c.toUpperCase());
+        if (err.details != null) {
+            const detail = typeof err.details === 'string' ? err.details : JSON.stringify(err.details);
+            return `${message}: ${detail}`;
+        }
+        return message;
+    }
     if (err instanceof Error) {
         return err.message;
     }

package/dist/src/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtE,4BAA4B;AAC5B,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,CAAC,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"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"}

package/dist/src/utils.spec.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=utils.spec.d.ts.map

package/dist/src/utils.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.spec.d.ts","sourceRoot":"","sources":["../../src/utils.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}