@techdigger/humanode-agentlink-cli 0.2.0

package/dist/lib/core.js

@@ -0,0 +1,435 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { stdin, stdout } from 'node:process';
+import { privateKeyToAccount } from 'viem/accounts';
+import { isAddress } from 'viem';
+import { createInterface } from 'node:readline/promises';
+import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { BIOMAPPER_APP_URLS } from '@techdigger/humanode-agentlink';
+export const NETWORKS = {
+    base: {
+        label: 'Base mainnet',
+        biomapperAppUrl: BIOMAPPER_APP_URLS.base,
+    },
+    'base-sepolia': {
+        label: 'Base Sepolia',
+        biomapperAppUrl: BIOMAPPER_APP_URLS['base-sepolia'],
+    },
+};
+export const TEMPLATE_NAMES = ['langchain', 'vercel-ai-sdk', 'mcp'];
+export const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
+export const PACKAGE_SOURCE_NAMES = ['npm', 'local'];
+export class CliError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CliError';
+    }
+}
+function parseEnvValue(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function parseEnvFile(content) {
+    const env = {};
+    for (const rawLine of content.split(/\r?\n/u)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const normalizedLine = line.startsWith('export ') ? line.slice(7) : line;
+        const separator = normalizedLine.indexOf('=');
+        if (separator <= 0)
+            continue;
+        const key = normalizedLine.slice(0, separator).trim();
+        const value = normalizedLine.slice(separator + 1);
+        if (!key)
+            continue;
+        env[key] = parseEnvValue(value);
+    }
+    return env;
+}
+export async function loadEnvFiles(cwd, baseEnv = process.env) {
+    const envFromFiles = {};
+    for (const name of ['.env', '.env.local']) {
+        const filePath = path.join(cwd, name);
+        try {
+            Object.assign(envFromFiles, parseEnvFile(await readFile(filePath, 'utf8')));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    return {
+        ...envFromFiles,
+        ...baseEnv,
+    };
+}
+export function parseFlags(argv) {
+    const args = [...argv];
+    const positionals = [];
+    const values = {};
+    const flags = new Set();
+    while (args.length > 0) {
+        const token = args.shift();
+        if (token === '--help' || token === '-h') {
+            flags.add('help');
+            continue;
+        }
+        if (!token.startsWith('--')) {
+            positionals.push(token);
+            continue;
+        }
+        const name = token.slice(2);
+        if (!name) {
+            throw new CliError('Unexpected empty flag name.');
+        }
+        const next = args[0];
+        if (!next || next.startsWith('--')) {
+            flags.add(name);
+            continue;
+        }
+        values[name] = args.shift();
+    }
+    return { positionals, values, flags };
+}
+export function assertNoExtraPositionals(command, positionals) {
+    if (positionals.length > 0) {
+        throw new CliError(`Unexpected argument${positionals.length > 1 ? 's' : ''} for ${command}: ${positionals.join(', ')}`);
+    }
+}
+export function resolveNetwork(value, env) {
+    const candidate = value ?? env.BIOMAPPER_NETWORK ?? 'base-sepolia';
+    if (!(candidate in NETWORKS)) {
+        throw new CliError(`Invalid --network. Expected one of: ${Object.keys(NETWORKS).join(', ')}`);
+    }
+    return candidate;
+}
+export function parseRequiredAddress(name, value) {
+    if (!value) {
+        throw new CliError(`Missing --${name}.`);
+    }
+    if (!isAddress(value)) {
+        throw new CliError(`Invalid --${name}. Expected a checksummed or lowercase EVM address.`);
+    }
+    return value;
+}
+export function parseAddressOrPlaceholder(name, value, fallback) {
+    const candidate = value?.trim() || fallback;
+    if (candidate === fallback)
+        return candidate;
+    if (!isAddress(candidate)) {
+        throw new CliError(`Invalid ${name}. Expected a checksummed or lowercase EVM address.`);
+    }
+    return candidate;
+}
+export function resolveRegistryAddress(value, env) {
+    return parseRequiredAddress('registry', value ?? env.BIOMAPPER_REGISTRY);
+}
+export function resolveRpcUrl(value, env) {
+    return value ?? env.BIOMAPPER_RPC_URL;
+}
+export function resolveLinkerUrl(value, env) {
+    return value ?? env.BIOMAPPER_LINKER_URL ?? 'http://localhost:5173/';
+}
+export function normalizePrivateKey(value) {
+    if (!value) {
+        throw new CliError('Missing agent private key. Pass --private-key, pipe it with --private-key-stdin, or set AGENT_PRIVATE_KEY.');
+    }
+    const normalized = value.startsWith('0x') ? value : `0x${value}`;
+    if (!/^0x[0-9a-fA-F]{64}$/u.test(normalized)) {
+        throw new CliError('Invalid private key. Expected a 32-byte hex string.');
+    }
+    return normalized;
+}
+export function resolvePrivateKey(value, env, override) {
+    return normalizePrivateKey(override ?? value ?? env.AGENT_PRIVATE_KEY);
+}
+export function deriveAgentAddress(privateKey) {
+    return privateKeyToAccount(privateKey).address;
+}
+export function resolveAgentAddress(agent, privateKey, env) {
+    if (agent) {
+        return parseRequiredAddress('agent', agent);
+    }
+    return deriveAgentAddress(resolvePrivateKey(privateKey, env));
+}
+export function parseFutureDeadline(value, now) {
+    if (!value) {
+        throw new CliError('Missing --deadline.');
+    }
+    if (!/^\d+$/u.test(value)) {
+        throw new CliError('Invalid --deadline. Expected unix seconds.');
+    }
+    const deadline = BigInt(value);
+    const nowSeconds = BigInt(Math.floor(now.getTime() / 1000));
+    if (deadline <= nowSeconds) {
+        throw new CliError('Invalid --deadline. The timestamp must be in the future.');
+    }
+    return deadline;
+}
+export function defaultDeadline(now, hours = 24) {
+    return BigInt(Math.floor(now.getTime() / 1000) + hours * 60 * 60);
+}
+export function formatJson(value) {
+    return JSON.stringify(value, null, 2);
+}
+const PM_COMMANDS = {
+    npm: { install: 'npm install', run: 'npm run' },
+    pnpm: { install: 'pnpm install', run: 'pnpm run' },
+    yarn: { install: 'yarn install', run: 'yarn run' },
+    bun: { install: 'bun install', run: 'bun run' },
+};
+export function getPackageManagerInstallCommand(packageManager) {
+    return PM_COMMANDS[packageManager].install;
+}
+export function getPackageManagerRunCommand(packageManager, script) {
+    return `${PM_COMMANDS[packageManager].run} ${script}`;
+}
+const HUMANODE_PACKAGE_VERSION = '^0.2.0';
+const HUMANODE_PACKAGE_META = {
+    agentlink: { dirName: 'agentlink', packageName: '@techdigger/humanode-agentlink', version: HUMANODE_PACKAGE_VERSION },
+    langchain: {
+        dirName: 'langchain',
+        packageName: '@techdigger/humanode-agentlink-langchain',
+        version: HUMANODE_PACKAGE_VERSION,
+    },
+    aiSdk: { dirName: 'ai-sdk', packageName: '@techdigger/humanode-agentlink-ai-sdk', version: HUMANODE_PACKAGE_VERSION },
+    mcp: { dirName: 'mcp', packageName: '@techdigger/humanode-agentlink-mcp', version: HUMANODE_PACKAGE_VERSION },
+    cli: { dirName: 'cli', packageName: '@techdigger/humanode-agentlink-cli', version: HUMANODE_PACKAGE_VERSION },
+};
+async function pathExists(targetPath) {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+async function directoryMatchesPackageName(targetPath, packageName) {
+    try {
+        const packageJson = JSON.parse(await readFile(path.join(targetPath, 'package.json'), 'utf8'));
+        return packageJson.name === packageName;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+function toFileDependency(fromDir, targetPath) {
+    const relativePath = path.relative(fromDir, targetPath).split(path.sep).join('/');
+    return `file:${relativePath || '.'}`;
+}
+export function resolvePackageSource(value) {
+    if (value === undefined)
+        return undefined;
+    if (!PACKAGE_SOURCE_NAMES.includes(value)) {
+        throw new CliError(`Invalid --package-source. Expected one of: ${PACKAGE_SOURCE_NAMES.join(', ')}`);
+    }
+    return value;
+}
+export async function resolveHumanodePackageSpecs(targetDir, requestedSource) {
+    const cliPackageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+    const monorepoRoot = path.resolve(cliPackageRoot, '..');
+    const localPackageDirs = Object.fromEntries(Object.entries(HUMANODE_PACKAGE_META).map(([key, meta]) => [key, path.join(monorepoRoot, meta.dirName)]));
+    const localPackageChecks = await Promise.all(Object.keys(HUMANODE_PACKAGE_META).map(async (key) => {
+        const meta = HUMANODE_PACKAGE_META[key];
+        const directory = localPackageDirs[key];
+        return (await pathExists(directory)) && (await directoryMatchesPackageName(directory, meta.packageName));
+    }));
+    const localPackagesAvailable = localPackageChecks.every(Boolean);
+    const packageSource = requestedSource ?? (localPackagesAvailable ? 'local' : 'npm');
+    if (packageSource === 'local' && !localPackagesAvailable) {
+        throw new CliError('Local package sources are not available from this CLI install. Re-run without --package-source local.');
+    }
+    if (packageSource === 'local') {
+        return {
+            packageSource,
+            packages: {
+                agentlink: toFileDependency(targetDir, localPackageDirs.agentlink),
+                langchain: toFileDependency(targetDir, localPackageDirs.langchain),
+                aiSdk: toFileDependency(targetDir, localPackageDirs.aiSdk),
+                mcp: toFileDependency(targetDir, localPackageDirs.mcp),
+                cli: toFileDependency(targetDir, localPackageDirs.cli),
+            },
+        };
+    }
+    return {
+        packageSource,
+        packages: {
+            agentlink: HUMANODE_PACKAGE_META.agentlink.version,
+            langchain: HUMANODE_PACKAGE_META.langchain.version,
+            aiSdk: HUMANODE_PACKAGE_META.aiSdk.version,
+            mcp: HUMANODE_PACKAGE_META.mcp.version,
+            cli: HUMANODE_PACKAGE_META.cli.version,
+        },
+    };
+}
+export function toPackageName(value) {
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._/-]+/gu, '-')
+        .replace(/\/+/gu, '/')
+        .replace(/^-+|-+$/gu, '')
+        .replace(/\/-+/gu, '/');
+    if (!normalized) {
+        throw new CliError('Project name cannot be empty.');
+    }
+    return normalized;
+}
+export async function ensureTargetDirectoryIsWritable(targetDir) {
+    try {
+        await access(targetDir);
+        const entries = await readdir(targetDir);
+        if (entries.length > 0) {
+            throw new CliError(`Refusing to overwrite a non-empty directory: ${targetDir}`);
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+}
+export async function writeGeneratedFiles(targetDir, files) {
+    await mkdir(targetDir, { recursive: true });
+    for (const file of files) {
+        const destination = path.join(targetDir, file.path);
+        await mkdir(path.dirname(destination), { recursive: true });
+        await writeFile(destination, file.content, 'utf8');
+    }
+}
+export function createConsolePrompter() {
+    if (!stdin.isTTY || !stdout.isTTY) {
+        throw new CliError('Interactive prompts require a TTY. Re-run with --yes and explicit flags in non-interactive environments.');
+    }
+    const rl = createInterface({ input: stdin, output: stdout });
+    return {
+        async text({ message, defaultValue, allowEmpty = false }) {
+            while (true) {
+                const suffix = defaultValue ? ` [${defaultValue}]` : '';
+                const answer = (await rl.question(`${message}${suffix}: `)).trim();
+                if (!answer && defaultValue !== undefined)
+                    return defaultValue;
+                if (answer || allowEmpty)
+                    return answer;
+            }
+        },
+        async select({ message, options, defaultValue }) {
+            const defaultIndex = options.findIndex(option => option.value === defaultValue);
+            stdout.write(`${message}\n`);
+            for (const [index, option] of options.entries()) {
+                const marker = option.value === defaultValue ? ' (default)' : '';
+                stdout.write(`  ${index + 1}. ${option.label}${marker}\n`);
+            }
+            while (true) {
+                const answer = (await rl.question(`Choose [${defaultIndex + 1}]: `)).trim();
+                if (!answer)
+                    return defaultValue;
+                const numeric = Number(answer);
+                if (Number.isInteger(numeric) && numeric >= 1 && numeric <= options.length) {
+                    return options[numeric - 1].value;
+                }
+            }
+        },
+        async confirm({ message, defaultValue = true }) {
+            const suffix = defaultValue ? ' [Y/n]' : ' [y/N]';
+            while (true) {
+                const answer = (await rl.question(`${message}${suffix}: `)).trim().toLowerCase();
+                if (!answer)
+                    return defaultValue;
+                if (['y', 'yes'].includes(answer))
+                    return true;
+                if (['n', 'no'].includes(answer))
+                    return false;
+            }
+        },
+        close() {
+            rl.close();
+        },
+    };
+}
+function spawnCommand(command, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            detached: options.detached,
+            stdio: options.stdio,
+        });
+        child.once('error', reject);
+        child.once('spawn', () => {
+            if (options.detached) {
+                child.unref();
+            }
+            resolve();
+        });
+    });
+}
+export async function openUrlInBrowser(url) {
+    if (process.platform === 'darwin') {
+        await spawnCommand('open', [url], { detached: true, stdio: 'ignore' });
+        return;
+    }
+    if (process.platform === 'win32') {
+        await spawnCommand('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' });
+        return;
+    }
+    await spawnCommand('xdg-open', [url], { detached: true, stdio: 'ignore' });
+}
+export async function readAllFromStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stdin.on('data', chunk => {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        stdin.once('error', reject);
+        stdin.once('end', () => {
+            resolve(Buffer.concat(chunks).toString('utf8'));
+        });
+    });
+}
+export async function installProjectDependencies(packageManager, cwd) {
+    const [command, ...args] = getPackageManagerInstallCommand(packageManager).split(' ');
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            stdio: 'inherit',
+        });
+        child.once('error', reject);
+        child.once('exit', code => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new CliError(`${command} exited with code ${code ?? 1}.`));
+        });
+    });
+}
+export function resolvePackageManager(value) {
+    if (value === undefined)
+        return undefined;
+    if (!PACKAGE_MANAGERS.includes(value)) {
+        throw new CliError(`Invalid --package-manager. Expected one of: ${PACKAGE_MANAGERS.join(', ')}`);
+    }
+    return value;
+}
+export function resolveTemplateName(value) {
+    if (value === undefined)
+        return undefined;
+    if (!TEMPLATE_NAMES.includes(value)) {
+        throw new CliError(`Invalid --template. Expected one of: ${TEMPLATE_NAMES.join(', ')}`);
+    }
+    return value;
+}

package/dist/lib/telemetry.d.ts

@@ -0,0 +1,13 @@
+import { type EnvSource, type NetworkName } from './core.js';
+export interface CliTelemetryInput {
+    eventName: string;
+    stage: string;
+    network?: NetworkName;
+    audience?: 'agent-developers' | 'platform-operators' | 'end-users' | 'community';
+    source?: string;
+    campaign?: string;
+    contentId?: string;
+    packageName?: string;
+    properties?: Record<string, unknown>;
+}
+export declare function captureCliTelemetry(input: CliTelemetryInput, env: EnvSource): Promise<void>;

package/dist/lib/telemetry.js

@@ -0,0 +1,123 @@
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { PostHog } from 'posthog-node';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createConsolePrompter } from './core.js';
+const DEFAULT_POSTHOG_HOST = 'https://us.i.posthog.com';
+const TELEMETRY_CONFIG_PATH = path.join(homedir(), '.config', 'agentlink', 'telemetry.json');
+function resolvePreferenceOverride(env) {
+    const candidate = env.AGENTLINK_TELEMETRY?.trim().toLowerCase();
+    if (candidate === 'on' || candidate === 'off') {
+        return candidate;
+    }
+    return null;
+}
+function resolveTelemetryConfig(env) {
+    const apiKey = env.AGENTLINK_POSTHOG_KEY?.trim();
+    if (!apiKey) {
+        return null;
+    }
+    return {
+        apiKey,
+        host: env.AGENTLINK_POSTHOG_HOST?.trim() || DEFAULT_POSTHOG_HOST,
+    };
+}
+async function readStoredPreference(filePath = TELEMETRY_CONFIG_PATH) {
+    try {
+        const parsed = JSON.parse(await readFile(filePath, 'utf8'));
+        if (typeof parsed.anonymousId === 'string' &&
+            parsed.anonymousId.length > 0 &&
+            (parsed.preference === 'on' || parsed.preference === 'off')) {
+            return {
+                anonymousId: parsed.anonymousId,
+                preference: parsed.preference,
+                updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date(0).toISOString(),
+            };
+        }
+        return null;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        return null;
+    }
+}
+async function writeStoredPreference(record, filePath = TELEMETRY_CONFIG_PATH) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+}
+async function promptForConsent(anonymousId, filePath = TELEMETRY_CONFIG_PATH) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return null;
+    }
+    const prompter = createConsolePrompter();
+    try {
+        const accepted = await prompter.confirm({
+            message: 'Share anonymous CLI usage telemetry to improve Biomapper Link? Override anytime with AGENTLINK_TELEMETRY=on|off',
+            defaultValue: false,
+        });
+        const record = {
+            anonymousId,
+            preference: accepted ? 'on' : 'off',
+            updatedAt: new Date().toISOString(),
+        };
+        await writeStoredPreference(record, filePath);
+        return accepted ? record : null;
+    }
+    finally {
+        prompter.close();
+    }
+}
+export async function captureCliTelemetry(input, env) {
+    const config = resolveTelemetryConfig(env);
+    if (!config) {
+        return;
+    }
+    const storedPreference = await readStoredPreference();
+    const override = resolvePreferenceOverride(env);
+    let anonymousId = storedPreference?.anonymousId ?? randomUUID();
+    let preference = override ?? storedPreference?.preference ?? null;
+    if (preference == null) {
+        const prompted = await promptForConsent(anonymousId);
+        if (!prompted) {
+            return;
+        }
+        preference = prompted.preference;
+        anonymousId = prompted.anonymousId;
+    }
+    if (preference !== 'on') {
+        return;
+    }
+    const timestamp = new Date().toISOString();
+    const event = {
+        event_name: input.eventName,
+        anonymous_id: anonymousId,
+        audience: input.audience ?? 'agent-developers',
+        source: input.source ?? env.AGENTLINK_SOURCE ?? 'cli',
+        campaign: input.campaign ?? env.AGENTLINK_CAMPAIGN ?? 'activation',
+        content_id: input.contentId ?? env.AGENTLINK_CONTENT_ID ?? `cli:${input.stage}`,
+        package: input.packageName ?? '@techdigger/humanode-agentlink-cli',
+        network: input.network ?? null,
+        stage: input.stage,
+        timestamp,
+        ...input.properties,
+    };
+    try {
+        const client = new PostHog(config.apiKey, {
+            host: config.host,
+            flushAt: 1,
+            flushInterval: 0,
+        });
+        client.capture({
+            distinctId: anonymousId,
+            event: input.eventName,
+            properties: event,
+        });
+        await client.shutdown();
+    }
+    catch {
+        // Telemetry failures should never block CLI flows.
+    }
+}

package/dist/templates.d.ts

@@ -0,0 +1,12 @@
+import type { GeneratedFile, HumanodePackageSpecs, NetworkName, PackageManager, PackageSourceName, TemplateName } from './lib/core.js';
+export interface TemplateInput {
+    projectName: string;
+    packageName: string;
+    template: TemplateName;
+    network: NetworkName;
+    registry: string;
+    packageManager: PackageManager;
+    packageSource: PackageSourceName;
+    humanodePackages: HumanodePackageSpecs;
+}
+export declare function buildTemplateFiles(input: TemplateInput): GeneratedFile[];