@ethogram/cli 0.1.0-alpha.0

package/dist/typescript-adapter.js

@@ -0,0 +1,373 @@
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { build } from 'esbuild';
+import { ExternalEvidenceValidationError, normalizeExternalExecutionEvidence, } from './external-evidence.js';
+export class TypeScriptAdapterError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TypeScriptAdapterError';
+    }
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object');
+}
+function isAgent(value) {
+    return isRecord(value)
+        && typeof value.id === 'string'
+        && typeof value.name === 'string'
+        && typeof value.description === 'string'
+        && typeof value.icon === 'string';
+}
+function isGivenValue(value, ancestors) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'object' || ancestors.has(value))
+        return false;
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.every((entry, index) => Object.prototype.hasOwnProperty.call(value, index) && isGivenValue(entry, ancestors));
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        return Reflect.ownKeys(value).every((key) => {
+            if (typeof key !== 'string')
+                return false;
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            return Boolean(descriptor && !descriptor.get && !descriptor.set && isGivenValue(descriptor.value, ancestors));
+        });
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function isGiven(value) {
+    return Array.isArray(value)
+        ? value.every((entry) => typeof entry === 'string')
+        : isGivenValue(value, new Set()) && Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function isStory(value) {
+    return isRecord(value)
+        && value.__ethogramType === 'story'
+        && typeof value.id === 'string'
+        && typeof value.name === 'string'
+        && isAgent(value.agent)
+        && typeof value.description === 'string'
+        && isGiven(value.given)
+        && typeof value.prompt === 'string'
+        && Array.isArray(value.expectations);
+}
+function isProfile(value) {
+    return isRecord(value)
+        && value.__ethogramType === 'execution-profile'
+        && typeof value.id === 'string'
+        && isRecord(value.tools)
+        && typeof value.execute === 'function';
+}
+function cloneRecord(value) {
+    return structuredClone(value);
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+    }
+    return value;
+}
+async function allFiles(root, directories) {
+    const files = [];
+    async function visit(directory) {
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === 'node_modules' || entry.name === '.git')
+                continue;
+            const absolute = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                await visit(absolute);
+            else
+                files.push(absolute);
+        }
+    }
+    for (const directory of directories)
+        await visit(path.resolve(root, directory));
+    return [...new Set(files)].sort();
+}
+function matches(filePath, stem) {
+    return ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'].some((extension) => filePath.endsWith(`${stem}${extension}`));
+}
+async function importNativeModule(filePath) {
+    try {
+        const result = await build({
+            entryPoints: [filePath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: 'node20',
+            write: false,
+            sourcemap: false,
+            logLevel: 'silent',
+        });
+        const source = result.outputFiles[0]?.contents;
+        if (!source)
+            throw new Error('The TypeScript adapter produced no executable module.');
+        const moduleUrl = `data:text/javascript;base64,${Buffer.from(source).toString('base64')}`;
+        return await import(moduleUrl);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message.split('\n')[0] : 'Unknown module-loading error.';
+        throw new TypeScriptAdapterError(filePath.includes('.stories.') ? 'INVALID_STORY_EXPORT' : 'INVALID_EXECUTION_PROFILE_EXPORT', `Could not load ${filePath}: ${detail}`);
+    }
+}
+function uniqueById(values, code, label) {
+    const seen = new Set();
+    for (const item of values) {
+        if (seen.has(item.value.id))
+            throw new TypeScriptAdapterError(code, `Duplicate ${label} identity: ${item.value.id}`);
+        seen.add(item.value.id);
+    }
+    return values;
+}
+function relative(root, filePath) {
+    return path.relative(root, filePath).split(path.sep).join('/');
+}
+function toToolCall(invocation) {
+    const base = {
+        callId: invocation.callId,
+        name: invocation.name,
+        duration: `${invocation.durationMs}ms`,
+        input: JSON.stringify(invocation.input),
+        startedAt: invocation.startedAt,
+        endedAt: invocation.endedAt,
+    };
+    return invocation.status === 'success'
+        ? { ...base, status: 'success', output: JSON.stringify(invocation.output) }
+        : { ...base, status: 'error', ...(invocation.error === undefined ? {} : { error: invocation.error }) };
+}
+export class TypeScriptAdapter {
+    id = 'typescript';
+    bindings = new Map();
+    async loadProject(projectRoot) {
+        let root;
+        try {
+            root = await realpath(projectRoot);
+            if (!(await stat(root)).isDirectory())
+                throw new Error('not-directory');
+        }
+        catch {
+            throw new TypeScriptAdapterError('INVALID_PROJECT_ROOT', `Project root is not a readable directory: ${path.resolve(projectRoot)}`);
+        }
+        let packageName;
+        try {
+            const packageJson = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+            if (typeof packageJson.name !== 'string' || !packageJson.name.trim())
+                throw new Error('missing-name');
+            packageName = packageJson.name;
+        }
+        catch {
+            throw new TypeScriptAdapterError('MISSING_PROJECT_PACKAGE', `Project ${root} must contain a package.json with a name.`);
+        }
+        const configPath = path.join(root, 'ethogram.config.mjs');
+        try {
+            if (!(await stat(configPath)).isFile())
+                throw new Error('not-file');
+        }
+        catch {
+            throw new TypeScriptAdapterError('MISSING_ETHOGRAM_CONFIG', `Project ${root} is not initialized. Run "ethogram init" first.`);
+        }
+        let config;
+        try {
+            const module = await importNativeModule(configPath);
+            if (!isRecord(module.default))
+                throw new Error('missing-default');
+            config = module.default;
+        }
+        catch (error) {
+            if (error instanceof TypeScriptAdapterError) {
+                throw new TypeScriptAdapterError('INVALID_ETHOGRAM_CONFIG', `Invalid ethogram.config.mjs in ${root}: ${error.message}`);
+            }
+            throw new TypeScriptAdapterError('INVALID_ETHOGRAM_CONFIG', `Invalid ethogram.config.mjs in ${root}.`);
+        }
+        const agentDirectories = config.agentDirectories ?? ['agents'];
+        const storyDirectories = config.storyDirectories ?? ['stories'];
+        const executionDirectories = config.executionDirectories ?? ['execution'];
+        if (![agentDirectories, storyDirectories, executionDirectories].every((entries) => Array.isArray(entries) && entries.every((entry) => typeof entry === 'string' && entry.length > 0))) {
+            throw new TypeScriptAdapterError('INVALID_ETHOGRAM_CONFIG', 'Ethogram directory configuration must contain string arrays.');
+        }
+        const [agentFiles, storyFiles, profileFiles] = await Promise.all([
+            allFiles(root, agentDirectories),
+            allFiles(root, storyDirectories),
+            allFiles(root, executionDirectories),
+        ]);
+        const selectedAgentFiles = agentFiles.filter((file) => matches(file, '.agent'));
+        const selectedStoryFiles = storyFiles.filter((file) => matches(file, '.agent.stories'));
+        const selectedProfileFiles = profileFiles.filter((file) => matches(file, '.profile') || matches(file, '-profile'));
+        const agentEntries = (await Promise.all(selectedAgentFiles.map(async (file) => {
+            const module = await importNativeModule(file);
+            const values = Object.values(module).filter(isAgent);
+            if (values.length === 0) {
+                throw new TypeScriptAdapterError('INVALID_AGENT_EXPORT', `No valid Agent export found in ${relative(root, file)}.`);
+            }
+            return values.map((value) => ({ value, source: relative(root, file) }));
+        }))).flat();
+        const storyEntries = (await Promise.all(selectedStoryFiles.map(async (file) => {
+            const module = await importNativeModule(file);
+            const values = Object.values(module).filter(isStory);
+            if (values.length === 0) {
+                throw new TypeScriptAdapterError('INVALID_STORY_EXPORT', `No valid Story export found in ${relative(root, file)}.`);
+            }
+            return values.map((value) => ({ value, source: relative(root, file) }));
+        }))).flat();
+        const profileEntries = (await Promise.all(selectedProfileFiles.map(async (file) => {
+            const module = await importNativeModule(file);
+            const values = Object.values(module).filter(isProfile);
+            if (values.length === 0) {
+                throw new TypeScriptAdapterError('INVALID_EXECUTION_PROFILE_EXPORT', `No valid execution profile export found in ${relative(root, file)}.`);
+            }
+            return values.map((value) => ({ value, source: relative(root, file) }));
+        }))).flat();
+        const agents = uniqueById(agentEntries, 'DUPLICATE_AGENT_ID', 'Agent');
+        const stories = uniqueById(storyEntries, 'DUPLICATE_STORY_ID', 'Story');
+        const profiles = uniqueById(profileEntries, 'DUPLICATE_EXECUTION_PROFILE_ID', 'execution profile');
+        if (stories.length === 0)
+            throw new TypeScriptAdapterError('NO_STORIES', `No Ethogram Stories were found in ${root}.`);
+        const agentIds = new Set(agents.map(({ value }) => value.id));
+        const profilesById = new Map(profiles.map(({ value }) => [value.id, value]));
+        this.bindings = new Map();
+        const descriptors = stories.map(({ value: story, source }) => {
+            deepFreeze(story);
+            if (!agentIds.has(story.agent.id)) {
+                throw new TypeScriptAdapterError('UNKNOWN_STORY_AGENT', `Story ${story.id} references unknown Agent ${story.agent.id}.`);
+            }
+            const profileId = story.execution?.profile;
+            const profile = profileId ? profilesById.get(profileId) : undefined;
+            if (!profile) {
+                throw new TypeScriptAdapterError('UNKNOWN_EXECUTION_PROFILE', `Story ${story.id} references unavailable execution profile ${profileId ?? '(none)'}.`);
+            }
+            this.bindings.set(story.id, { story, profile });
+            return structuredClone({
+                id: story.id,
+                name: story.name,
+                agent: story.agent,
+                description: story.description,
+                given: story.given,
+                prompt: story.prompt,
+                expectations: story.expectations,
+                source,
+                executable: true,
+            });
+        });
+        return {
+            projectRoot: root,
+            name: typeof config.name === 'string' && config.name.trim() ? config.name : packageName,
+            adapter: { id: this.id, label: 'TypeScript' },
+            agents: agents.map(({ value }) => structuredClone(value)),
+            stories: descriptors,
+        };
+    }
+    async run(request) {
+        const binding = this.bindings.get(request.story.id);
+        if (!binding)
+            throw new TypeScriptAdapterError('UNKNOWN_EXECUTION_PROFILE', `No TypeScript binding exists for ${request.story.id}.`);
+        const trace = [];
+        const startedAtMs = Date.now();
+        try {
+            const outcome = await binding.profile.execute({
+                story: binding.story,
+                callTool: async (name, input) => {
+                    const tool = binding.profile.tools[name];
+                    if (!tool)
+                        throw new Error(`Execution profile requested unavailable tool: ${name}`);
+                    const callStartedMs = Date.now();
+                    const invocation = {
+                        callId: `typescript-${trace.length + 1}`,
+                        name,
+                        input: cloneRecord(input),
+                        status: 'success',
+                        startedAt: new Date(callStartedMs).toISOString(),
+                        endedAt: '',
+                        durationMs: 0,
+                    };
+                    trace.push(invocation);
+                    try {
+                        const output = await tool.execute(cloneRecord(input));
+                        invocation.output = cloneRecord(output);
+                        return cloneRecord(output);
+                    }
+                    catch (error) {
+                        invocation.status = 'error';
+                        invocation.output = undefined;
+                        invocation.error = error instanceof Error
+                            ? { name: error.name, message: error.message }
+                            : { message: 'The tool execution failed.' };
+                        throw error;
+                    }
+                    finally {
+                        const endedAtMs = Date.now();
+                        invocation.endedAt = new Date(endedAtMs).toISOString();
+                        invocation.durationMs = Math.max(0, endedAtMs - callStartedMs);
+                    }
+                },
+            });
+            if (outcome.evidence !== undefined && trace.length > 0) {
+                throw new TypeScriptAdapterError('CONFLICTING_OBSERVATION_SOURCES', 'CONFLICTING_OBSERVATION_SOURCES: A Run cannot use both Ethogram callTool evidence and external execution evidence.');
+            }
+            const endedAtMs = Date.now();
+            if (outcome.evidence !== undefined) {
+                let normalized;
+                try {
+                    normalized = normalizeExternalExecutionEvidence(outcome.evidence);
+                }
+                catch (error) {
+                    if (error instanceof ExternalEvidenceValidationError) {
+                        throw new TypeScriptAdapterError(error.code, error.message);
+                    }
+                    throw error;
+                }
+                return {
+                    decision: outcome.decision,
+                    reason: outcome.finalResponse,
+                    finalResponse: outcome.finalResponse,
+                    ...normalized,
+                };
+            }
+            return {
+                decision: outcome.decision,
+                reason: outcome.finalResponse,
+                finalResponse: outcome.finalResponse,
+                toolCalls: trace.map(toToolCall),
+                timeline: trace.map((invocation) => ({
+                    label: `Tool completed: ${invocation.name}`,
+                    detail: `Operational status: ${invocation.status}`,
+                    duration: `${invocation.durationMs}ms`,
+                })),
+                evidence: {
+                    provider: 'local-typescript-adapter',
+                    model: 'offline-deterministic-profile',
+                    startedAt: new Date(startedAtMs).toISOString(),
+                    endedAt: new Date(endedAtMs).toISOString(),
+                    latencyMs: Math.max(0, endedAtMs - startedAtMs),
+                    finishReason: 'completed',
+                    tokenUsage: { availability: 'unavailable' },
+                },
+            };
+        }
+        catch (error) {
+            if (error instanceof TypeScriptAdapterError)
+                throw error;
+            const detail = error instanceof Error ? error.message : 'Unknown profile execution error.';
+            throw new TypeScriptAdapterError('PROFILE_EXECUTION_FAILED', `TypeScript execution profile failed: ${detail}`);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ethogram/cli",
+  "version": "0.1.0-alpha.0",
+  "description": "Local Ethogram initialization and read-only developer runtime.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leonardocamacho1983/ethogram.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/leonardocamacho1983/ethogram#readme",
+  "bugs": {
+    "url": "https://github.com/leonardocamacho1983/ethogram/issues"
+  },
+  "keywords": ["ai-agents", "behavioral-testing", "typescript", "cli"],
+  "type": "module",
+  "bin": {
+    "ethogram": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.9"
+  },
+  "dependencies": {
+    "@ethogram/core": "0.1.0-alpha.0",
+    "esbuild": "^0.28.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-runtime.mjs"
+  }
+}