cli4ai 1.2.0 → 1.2.1

package/dist/core/remote-client.js

@@ -0,0 +1,252 @@
+/**
+ * Remote client for executing cli4ai commands on remote hosts.
+ *
+ * This module provides functions to call remote cli4ai services
+ * configured via `cli4ai remotes add`.
+ */
+import { request as httpRequest } from 'http';
+import { request as httpsRequest } from 'https';
+import { getRemoteOrThrow, updateRemoteLastConnected } from './remotes.js';
+// ═══════════════════════════════════════════════════════════════════════════
+// ERRORS
+// ═══════════════════════════════════════════════════════════════════════════
+export class RemoteConnectionError extends Error {
+    remoteName;
+    url;
+    constructor(remoteName, url, message) {
+        super(`Failed to connect to remote "${remoteName}" at ${url}: ${message}`);
+        this.remoteName = remoteName;
+        this.url = url;
+        this.name = 'RemoteConnectionError';
+    }
+}
+export class RemoteApiError extends Error {
+    remoteName;
+    statusCode;
+    code;
+    details;
+    constructor(remoteName, statusCode, code, message, details) {
+        super(`Remote "${remoteName}" error [${code}]: ${message}`);
+        this.remoteName = remoteName;
+        this.statusCode = statusCode;
+        this.code = code;
+        this.details = details;
+        this.name = 'RemoteApiError';
+    }
+}
+function makeRequest(url, method, headers, body, timeoutMs = 30000) {
+    return new Promise((resolve, reject) => {
+        const isHttps = url.protocol === 'https:';
+        const requestFn = isHttps ? httpsRequest : httpRequest;
+        const reqHeaders = {
+            ...headers,
+            'Content-Type': 'application/json'
+        };
+        if (body) {
+            reqHeaders['Content-Length'] = Buffer.byteLength(body);
+        }
+        const options = {
+            method,
+            hostname: url.hostname,
+            port: url.port || (isHttps ? 443 : 80),
+            path: url.pathname + url.search,
+            headers: reqHeaders,
+            timeout: timeoutMs
+        };
+        const req = requestFn(options, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+            res.on('end', () => {
+                resolve({
+                    statusCode: res.statusCode ?? 500,
+                    body: Buffer.concat(chunks).toString('utf-8')
+                });
+            });
+        });
+        req.on('error', (err) => {
+            reject(err);
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error('Request timeout'));
+        });
+        if (body) {
+            req.write(body);
+        }
+        req.end();
+    });
+}
+function buildHeaders(remote) {
+    const headers = {
+        'Accept': 'application/json'
+    };
+    if (remote.apiKey) {
+        headers['X-API-Key'] = remote.apiKey;
+    }
+    return headers;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// CLIENT FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Check health of a remote service
+ */
+export async function remoteHealth(remoteName) {
+    const remote = getRemoteOrThrow(remoteName);
+    const url = new URL('/health', remote.url);
+    try {
+        const response = await makeRequest(url, 'GET', buildHeaders(remote));
+        if (response.statusCode !== 200) {
+            const error = JSON.parse(response.body)?.error;
+            throw new RemoteApiError(remoteName, response.statusCode, error?.code ?? 'API_ERROR', error?.message ?? 'Unknown error', error?.details);
+        }
+        const data = JSON.parse(response.body);
+        updateRemoteLastConnected(remoteName);
+        return data;
+    }
+    catch (err) {
+        if (err instanceof RemoteApiError)
+            throw err;
+        throw new RemoteConnectionError(remoteName, remote.url, err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * List packages on a remote
+ */
+export async function remoteListPackages(remoteName) {
+    const remote = getRemoteOrThrow(remoteName);
+    const url = new URL('/packages', remote.url);
+    try {
+        const response = await makeRequest(url, 'GET', buildHeaders(remote));
+        if (response.statusCode !== 200) {
+            const error = JSON.parse(response.body)?.error;
+            throw new RemoteApiError(remoteName, response.statusCode, error?.code ?? 'API_ERROR', error?.message ?? 'Unknown error', error?.details);
+        }
+        updateRemoteLastConnected(remoteName);
+        return JSON.parse(response.body);
+    }
+    catch (err) {
+        if (err instanceof RemoteApiError)
+            throw err;
+        throw new RemoteConnectionError(remoteName, remote.url, err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * Get package info from a remote
+ */
+export async function remotePackageInfo(remoteName, packageName) {
+    const remote = getRemoteOrThrow(remoteName);
+    const url = new URL(`/packages/${encodeURIComponent(packageName)}`, remote.url);
+    try {
+        const response = await makeRequest(url, 'GET', buildHeaders(remote));
+        if (response.statusCode === 404) {
+            return null;
+        }
+        if (response.statusCode !== 200) {
+            const error = JSON.parse(response.body)?.error;
+            throw new RemoteApiError(remoteName, response.statusCode, error?.code ?? 'API_ERROR', error?.message ?? 'Unknown error', error?.details);
+        }
+        updateRemoteLastConnected(remoteName);
+        return JSON.parse(response.body);
+    }
+    catch (err) {
+        if (err instanceof RemoteApiError)
+            throw err;
+        throw new RemoteConnectionError(remoteName, remote.url, err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * Run a tool on a remote
+ */
+export async function remoteRunTool(remoteName, options) {
+    const remote = getRemoteOrThrow(remoteName);
+    const url = new URL('/run', remote.url);
+    const body = JSON.stringify({
+        package: options.package,
+        command: options.command,
+        args: options.args,
+        env: options.env,
+        stdin: options.stdin,
+        timeout: options.timeout,
+        scope: options.scope
+    });
+    // Use longer timeout for execution (tool timeout + network overhead)
+    const requestTimeout = (options.timeout ?? 30000) + 10000;
+    try {
+        const response = await makeRequest(url, 'POST', buildHeaders(remote), body, requestTimeout);
+        const data = JSON.parse(response.body);
+        // Check for API-level error
+        if (data.error && response.statusCode >= 400 && response.statusCode !== 500) {
+            throw new RemoteApiError(remoteName, response.statusCode, data.error.code ?? 'API_ERROR', data.error.message ?? 'Unknown error', data.error.details);
+        }
+        updateRemoteLastConnected(remoteName);
+        // Return the run result (may indicate success: false for tool failure)
+        return data;
+    }
+    catch (err) {
+        if (err instanceof RemoteApiError)
+            throw err;
+        throw new RemoteConnectionError(remoteName, remote.url, err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * Run a routine on a remote
+ */
+export async function remoteRunRoutine(remoteName, routineName, vars) {
+    const remote = getRemoteOrThrow(remoteName);
+    const url = new URL(`/routines/${encodeURIComponent(routineName)}/run`, remote.url);
+    const body = vars ? JSON.stringify({ vars }) : '{}';
+    try {
+        const response = await makeRequest(url, 'POST', buildHeaders(remote), body, 300000); // 5 min timeout for routines
+        if (response.statusCode === 404) {
+            throw new RemoteApiError(remoteName, 404, 'NOT_FOUND', `Routine not found: ${routineName}`);
+        }
+        const data = JSON.parse(response.body);
+        if (data.error && response.statusCode >= 400) {
+            throw new RemoteApiError(remoteName, response.statusCode, data.error.code ?? 'API_ERROR', data.error.message ?? 'Unknown error', data.error.details);
+        }
+        updateRemoteLastConnected(remoteName);
+        return data;
+    }
+    catch (err) {
+        if (err instanceof RemoteApiError)
+            throw err;
+        throw new RemoteConnectionError(remoteName, remote.url, err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * Test connection to a remote
+ */
+export async function testRemoteConnection(remoteName) {
+    try {
+        const health = await remoteHealth(remoteName);
+        return {
+            success: true,
+            message: `Connected to ${health.hostname}`,
+            details: {
+                hostname: health.hostname,
+                version: health.version,
+                uptime: health.uptime
+            }
+        };
+    }
+    catch (err) {
+        if (err instanceof RemoteConnectionError) {
+            return {
+                success: false,
+                message: err.message
+            };
+        }
+        if (err instanceof RemoteApiError) {
+            return {
+                success: false,
+                message: `${err.code}: ${err.message}`,
+                details: err.details
+            };
+        }
+        return {
+            success: false,
+            message: err instanceof Error ? err.message : String(err)
+        };
+    }
+}

package/dist/core/remotes.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Remote host configuration for distributed cli4ai execution.
+ *
+ * Manages named remote hosts that can execute cli4ai commands.
+ * Each remote is a cli4ai instance running `cli4ai serve`.
+ */
+export interface RemoteHost {
+    /** Unique name for this remote (e.g., "chrome-server", "gpu-box") */
+    name: string;
+    /** Base URL of the remote cli4ai service (e.g., "http://192.168.1.50:4100") */
+    url: string;
+    /** Optional API key for authentication */
+    apiKey?: string;
+    /** Optional description */
+    description?: string;
+    /** When this remote was added */
+    addedAt: string;
+    /** Last successful connection time */
+    lastConnected?: string;
+}
+export interface RemotesConfig {
+    version: 1;
+    remotes: RemoteHost[];
+}
+/**
+ * Load remotes configuration
+ */
+export declare function loadRemotesConfig(): RemotesConfig;
+/**
+ * Save remotes configuration
+ */
+export declare function saveRemotesConfig(config: RemotesConfig): void;
+export declare class RemoteNotFoundError extends Error {
+    remoteName: string;
+    constructor(remoteName: string);
+}
+export declare class RemoteAlreadyExistsError extends Error {
+    remoteName: string;
+    constructor(remoteName: string);
+}
+export declare class InvalidRemoteUrlError extends Error {
+    url: string;
+    reason: string;
+    constructor(url: string, reason: string);
+}
+/**
+ * Validate and normalize a remote URL
+ */
+export declare function validateRemoteUrl(url: string): string;
+/**
+ * Validate remote name (alphanumeric, dashes, underscores)
+ */
+export declare function validateRemoteName(name: string): void;
+/**
+ * Get all configured remotes
+ */
+export declare function getRemotes(): RemoteHost[];
+/**
+ * Get a remote by name
+ */
+export declare function getRemote(name: string): RemoteHost | null;
+/**
+ * Get a remote by name, throwing if not found
+ */
+export declare function getRemoteOrThrow(name: string): RemoteHost;
+/**
+ * Add a new remote
+ */
+export declare function addRemote(name: string, url: string, options?: {
+    apiKey?: string;
+    description?: string;
+}): RemoteHost;
+/**
+ * Update an existing remote
+ */
+export declare function updateRemote(name: string, updates: {
+    url?: string;
+    apiKey?: string;
+    description?: string;
+}): RemoteHost;
+/**
+ * Remove a remote
+ */
+export declare function removeRemote(name: string): void;
+/**
+ * Update last connected time for a remote
+ */
+export declare function updateRemoteLastConnected(name: string): void;

package/dist/core/remotes.js

@@ -0,0 +1,206 @@
+/**
+ * Remote host configuration for distributed cli4ai execution.
+ *
+ * Manages named remote hosts that can execute cli4ai commands.
+ * Each remote is a cli4ai instance running `cli4ai serve`.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { CLI4AI_HOME, ensureCli4aiHome } from './config.js';
+// ═══════════════════════════════════════════════════════════════════════════
+// PATHS
+// ═══════════════════════════════════════════════════════════════════════════
+const REMOTES_FILE = resolve(CLI4AI_HOME, 'remotes.json');
+// ═══════════════════════════════════════════════════════════════════════════
+// LOADING & SAVING
+// ═══════════════════════════════════════════════════════════════════════════
+const DEFAULT_REMOTES_CONFIG = {
+    version: 1,
+    remotes: []
+};
+/**
+ * Load remotes configuration
+ */
+export function loadRemotesConfig() {
+    ensureCli4aiHome();
+    if (!existsSync(REMOTES_FILE)) {
+        return { ...DEFAULT_REMOTES_CONFIG };
+    }
+    try {
+        const content = readFileSync(REMOTES_FILE, 'utf-8');
+        const data = JSON.parse(content);
+        // Validate and migrate if needed
+        if (!data.version || data.version !== 1) {
+            return { ...DEFAULT_REMOTES_CONFIG };
+        }
+        return data;
+    }
+    catch {
+        return { ...DEFAULT_REMOTES_CONFIG };
+    }
+}
+/**
+ * Save remotes configuration
+ */
+export function saveRemotesConfig(config) {
+    ensureCli4aiHome();
+    const content = JSON.stringify(config, null, 2) + '\n';
+    writeFileSync(REMOTES_FILE, content, { mode: 0o600 });
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// REMOTE MANAGEMENT
+// ═══════════════════════════════════════════════════════════════════════════
+export class RemoteNotFoundError extends Error {
+    remoteName;
+    constructor(remoteName) {
+        super(`Remote not found: ${remoteName}`);
+        this.remoteName = remoteName;
+        this.name = 'RemoteNotFoundError';
+    }
+}
+export class RemoteAlreadyExistsError extends Error {
+    remoteName;
+    constructor(remoteName) {
+        super(`Remote already exists: ${remoteName}`);
+        this.remoteName = remoteName;
+        this.name = 'RemoteAlreadyExistsError';
+    }
+}
+export class InvalidRemoteUrlError extends Error {
+    url;
+    reason;
+    constructor(url, reason) {
+        super(`Invalid remote URL "${url}": ${reason}`);
+        this.url = url;
+        this.reason = reason;
+        this.name = 'InvalidRemoteUrlError';
+    }
+}
+/**
+ * Validate and normalize a remote URL
+ */
+export function validateRemoteUrl(url) {
+    // Basic URL validation
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new InvalidRemoteUrlError(url, 'Not a valid URL');
+    }
+    // Only allow http and https
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new InvalidRemoteUrlError(url, 'Must use http or https protocol');
+    }
+    // Remove trailing slash for consistency
+    let normalized = parsed.origin;
+    if (parsed.pathname && parsed.pathname !== '/') {
+        normalized += parsed.pathname.replace(/\/$/, '');
+    }
+    return normalized;
+}
+/**
+ * Validate remote name (alphanumeric, dashes, underscores)
+ */
+export function validateRemoteName(name) {
+    if (!name || name.length === 0) {
+        throw new Error('Remote name cannot be empty');
+    }
+    if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name)) {
+        throw new Error('Remote name must start with a letter and contain only letters, numbers, dashes, and underscores');
+    }
+    if (name.length > 64) {
+        throw new Error('Remote name must be 64 characters or less');
+    }
+}
+/**
+ * Get all configured remotes
+ */
+export function getRemotes() {
+    const config = loadRemotesConfig();
+    return config.remotes;
+}
+/**
+ * Get a remote by name
+ */
+export function getRemote(name) {
+    const config = loadRemotesConfig();
+    return config.remotes.find(r => r.name === name) ?? null;
+}
+/**
+ * Get a remote by name, throwing if not found
+ */
+export function getRemoteOrThrow(name) {
+    const remote = getRemote(name);
+    if (!remote) {
+        throw new RemoteNotFoundError(name);
+    }
+    return remote;
+}
+/**
+ * Add a new remote
+ */
+export function addRemote(name, url, options) {
+    validateRemoteName(name);
+    const normalizedUrl = validateRemoteUrl(url);
+    const config = loadRemotesConfig();
+    // Check for duplicate name
+    if (config.remotes.some(r => r.name === name)) {
+        throw new RemoteAlreadyExistsError(name);
+    }
+    const remote = {
+        name,
+        url: normalizedUrl,
+        apiKey: options?.apiKey,
+        description: options?.description,
+        addedAt: new Date().toISOString()
+    };
+    config.remotes.push(remote);
+    saveRemotesConfig(config);
+    return remote;
+}
+/**
+ * Update an existing remote
+ */
+export function updateRemote(name, updates) {
+    const config = loadRemotesConfig();
+    const index = config.remotes.findIndex(r => r.name === name);
+    if (index === -1) {
+        throw new RemoteNotFoundError(name);
+    }
+    const remote = config.remotes[index];
+    if (updates.url !== undefined) {
+        remote.url = validateRemoteUrl(updates.url);
+    }
+    if (updates.apiKey !== undefined) {
+        remote.apiKey = updates.apiKey || undefined;
+    }
+    if (updates.description !== undefined) {
+        remote.description = updates.description || undefined;
+    }
+    saveRemotesConfig(config);
+    return remote;
+}
+/**
+ * Remove a remote
+ */
+export function removeRemote(name) {
+    const config = loadRemotesConfig();
+    const index = config.remotes.findIndex(r => r.name === name);
+    if (index === -1) {
+        throw new RemoteNotFoundError(name);
+    }
+    config.remotes.splice(index, 1);
+    saveRemotesConfig(config);
+}
+/**
+ * Update last connected time for a remote
+ */
+export function updateRemoteLastConnected(name) {
+    const config = loadRemotesConfig();
+    const remote = config.remotes.find(r => r.name === name);
+    if (remote) {
+        remote.lastConnected = new Date().toISOString();
+        saveRemotesConfig(config);
+    }
+}

package/dist/core/routine-engine.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Structured routine runner (v1).
+ */
+export declare class RoutineParseError extends Error {
+    path: string;
+    constructor(path: string, message: string);
+}
+export declare class RoutineValidationError extends Error {
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, details?: Record<string, unknown> | undefined);
+}
+export declare class RoutineTemplateError extends Error {
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, details?: Record<string, unknown> | undefined);
+}
+export type StepCapture = 'inherit' | 'text' | 'json';
+export interface RoutineSchedule {
+    /** Cron expression (e.g., "0 9 * * *" for 9am daily) */
+    cron?: string;
+    /** Simple interval (e.g., "30s", "5m", "1h", "1d") */
+    interval?: string;
+    /** IANA timezone (e.g., "Pacific/Auckland"). Defaults to system timezone */
+    timezone?: string;
+    /** Whether this schedule is active. Defaults to true */
+    enabled?: boolean;
+    /** Number of retry attempts on failure. Defaults to 0 */
+    retries?: number;
+    /** Delay between retries in milliseconds. Defaults to 60000 */
+    retryDelayMs?: number;
+    /** What to do if previous run is still executing. Defaults to 'skip' */
+    concurrency?: 'skip' | 'queue';
+}
+export interface RoutineVarDef {
+    default?: string;
+}
+export interface RoutineBaseStep {
+    id: string;
+    type: 'cli4ai' | 'set' | 'exec';
+    continueOnError?: boolean;
+    timeout?: number;
+}
+export interface RoutineC4aiStep extends RoutineBaseStep {
+    type: 'cli4ai';
+    package: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    stdin?: string;
+    capture?: StepCapture;
+    /** Name of a configured remote to execute on (optional) */
+    remote?: string;
+}
+export interface RoutineSetStep extends RoutineBaseStep {
+    type: 'set';
+    vars: Record<string, string>;
+}
+export interface RoutineExecStep extends RoutineBaseStep {
+    type: 'exec';
+    cmd: string;
+    args?: string[];
+    env?: Record<string, string>;
+    stdin?: string;
+    capture?: Exclude<StepCapture, 'inherit'>;
+}
+export type RoutineStep = RoutineC4aiStep | RoutineSetStep | RoutineExecStep;
+export interface RoutineDefinition {
+    version: 1;
+    name: string;
+    description?: string;
+    mcp?: {
+        expose?: boolean;
+        description?: string;
+    };
+    vars?: Record<string, RoutineVarDef>;
+    /** Schedule configuration for automatic execution */
+    schedule?: RoutineSchedule;
+    steps: RoutineStep[];
+    result?: unknown;
+}
+export interface StepRunResult {
+    id: string;
+    type: RoutineStep['type'];
+    status: 'success' | 'failed' | 'skipped';
+    exitCode?: number;
+    durationMs?: number;
+    stdout?: string;
+    stderr?: string;
+    json?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+export interface RoutineRunSummary {
+    routine: string;
+    version: number;
+    status: 'success' | 'failed';
+    exitCode: number;
+    durationMs: number;
+    vars: Record<string, unknown>;
+    steps: StepRunResult[];
+    result?: unknown;
+}
+export interface RoutineDryRunStep {
+    id: string;
+    type: RoutineStep['type'];
+    rendered: Record<string, unknown>;
+}
+export interface RoutineDryRunPlan {
+    routine: string;
+    version: number;
+    vars: Record<string, unknown>;
+    steps: RoutineDryRunStep[];
+    result?: unknown;
+}
+export declare function loadRoutineDefinition(path: string): RoutineDefinition;
+/**
+ * Validate a schedule configuration.
+ * Exported for use by scheduler and tests.
+ */
+export declare function validateScheduleConfig(schedule: unknown, source?: string): RoutineSchedule;
+export declare function dryRunRoutine(def: RoutineDefinition, vars: Record<string, string>, invocationDir: string): Promise<RoutineDryRunPlan>;
+export declare function runRoutine(def: RoutineDefinition, vars: Record<string, string>, invocationDir: string): Promise<RoutineRunSummary>;