optimal-cli 0.1.0 → 1.0.1

package/dist/lib/bot/protocol.d.ts

@@ -0,0 +1,12 @@
+export interface AgentMessage {
+    type: 'heartbeat' | 'claim' | 'progress' | 'complete' | 'blocked' | 'release';
+    agentId: string;
+    taskId?: string;
+    payload?: Record<string, unknown>;
+}
+export interface AgentResponse {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+export declare function processAgentMessage(msg: AgentMessage): Promise<AgentResponse>;

package/dist/lib/bot/protocol.js

@@ -0,0 +1,74 @@
+import { sendHeartbeat } from './heartbeat.js';
+import { claimNextTask, releaseTask } from './claim.js';
+import { reportProgress, reportCompletion, reportBlocked } from './reporter.js';
+// --- Message processor ---
+export async function processAgentMessage(msg) {
+    try {
+        switch (msg.type) {
+            case 'heartbeat':
+                return await handleHeartbeat(msg);
+            case 'claim':
+                return await handleClaim(msg);
+            case 'progress':
+                return await handleProgress(msg);
+            case 'complete':
+                return await handleComplete(msg);
+            case 'blocked':
+                return await handleBlocked(msg);
+            case 'release':
+                return await handleRelease(msg);
+            default:
+                return { success: false, error: `Unknown message type: ${msg.type}` };
+        }
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        return { success: false, error: errorMsg };
+    }
+}
+// --- Handlers ---
+async function handleHeartbeat(msg) {
+    const status = msg.payload?.status ?? 'idle';
+    await sendHeartbeat(msg.agentId, status);
+    return { success: true, data: { agentId: msg.agentId, status } };
+}
+async function handleClaim(msg) {
+    const skills = msg.payload?.skills;
+    const task = await claimNextTask(msg.agentId, skills);
+    if (!task) {
+        return { success: true, data: null };
+    }
+    return { success: true, data: { taskId: task.id, title: task.title } };
+}
+async function handleProgress(msg) {
+    if (!msg.taskId) {
+        return { success: false, error: 'taskId is required for progress messages' };
+    }
+    const message = msg.payload?.message ?? 'Progress update';
+    await reportProgress(msg.taskId, msg.agentId, message);
+    return { success: true, data: { taskId: msg.taskId } };
+}
+async function handleComplete(msg) {
+    if (!msg.taskId) {
+        return { success: false, error: 'taskId is required for complete messages' };
+    }
+    const summary = msg.payload?.summary ?? 'Task completed';
+    await reportCompletion(msg.taskId, msg.agentId, summary);
+    return { success: true, data: { taskId: msg.taskId, status: 'done' } };
+}
+async function handleBlocked(msg) {
+    if (!msg.taskId) {
+        return { success: false, error: 'taskId is required for blocked messages' };
+    }
+    const reason = msg.payload?.reason ?? 'No reason given';
+    await reportBlocked(msg.taskId, msg.agentId, reason);
+    return { success: true, data: { taskId: msg.taskId, status: 'blocked' } };
+}
+async function handleRelease(msg) {
+    if (!msg.taskId) {
+        return { success: false, error: 'taskId is required for release messages' };
+    }
+    const reason = msg.payload?.reason;
+    const task = await releaseTask(msg.taskId, msg.agentId, reason);
+    return { success: true, data: { taskId: task.id, status: 'ready' } };
+}

package/dist/lib/bot/reporter.d.ts

@@ -0,0 +1,3 @@
+export declare function reportProgress(taskId: string, agentId: string, message: string): Promise<void>;
+export declare function reportCompletion(taskId: string, agentId: string, summary: string): Promise<void>;
+export declare function reportBlocked(taskId: string, agentId: string, reason: string): Promise<void>;

package/dist/lib/bot/reporter.js

@@ -0,0 +1,27 @@
+import { addComment, updateTask, completeTask } from '../board/index.js';
+export async function reportProgress(taskId, agentId, message) {
+    await addComment({
+        task_id: taskId,
+        author: agentId,
+        body: message,
+        comment_type: 'comment',
+    });
+}
+export async function reportCompletion(taskId, agentId, summary) {
+    await completeTask(taskId, agentId);
+    await addComment({
+        task_id: taskId,
+        author: agentId,
+        body: summary,
+        comment_type: 'status_change',
+    });
+}
+export async function reportBlocked(taskId, agentId, reason) {
+    await updateTask(taskId, { status: 'blocked' }, agentId);
+    await addComment({
+        task_id: taskId,
+        author: agentId,
+        body: `Blocked: ${reason}`,
+        comment_type: 'status_change',
+    });
+}

package/dist/lib/bot/skills.d.ts

@@ -0,0 +1,26 @@
+import type { Task } from '../board/types.js';
+export interface AgentProfile {
+    id: string;
+    skills: string[];
+    maxConcurrent: number;
+    status: 'idle' | 'working' | 'error';
+}
+/**
+ * Reads agent profiles from agents/profiles.json.
+ * Falls back to a single default wildcard profile if the file doesn't exist.
+ */
+export declare function getAgentProfiles(): AgentProfile[];
+/**
+ * Filters and ranks tasks an agent can work on.
+ *
+ * - Includes tasks whose skill_required is in the agent's skills list,
+ *   or tasks with no skill_required, or if agent has wildcard '*'.
+ * - Sorts by priority (P1 first), then sort_order.
+ * - Returns at most agent.maxConcurrent tasks.
+ */
+export declare function matchTasksToAgent(agent: AgentProfile, tasks: Task[]): Task[];
+/**
+ * Finds the first idle agent whose skills match the task's skill_required.
+ * Returns null if no suitable idle agent exists.
+ */
+export declare function findBestAgent(profiles: AgentProfile[], task: Task): AgentProfile | null;

package/dist/lib/bot/skills.js

@@ -0,0 +1,69 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const DEFAULT_PROFILE = {
+    id: 'default',
+    skills: ['*'],
+    maxConcurrent: 1,
+    status: 'idle',
+};
+/**
+ * Reads agent profiles from agents/profiles.json.
+ * Falls back to a single default wildcard profile if the file doesn't exist.
+ */
+export function getAgentProfiles() {
+    const root = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const profilesPath = resolve(root, 'agents', 'profiles.json');
+    if (!existsSync(profilesPath)) {
+        return [DEFAULT_PROFILE];
+    }
+    try {
+        const raw = readFileSync(profilesPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch {
+        return [DEFAULT_PROFILE];
+    }
+}
+/**
+ * Filters and ranks tasks an agent can work on.
+ *
+ * - Includes tasks whose skill_required is in the agent's skills list,
+ *   or tasks with no skill_required, or if agent has wildcard '*'.
+ * - Sorts by priority (P1 first), then sort_order.
+ * - Returns at most agent.maxConcurrent tasks.
+ */
+export function matchTasksToAgent(agent, tasks) {
+    const hasWildcard = agent.skills.includes('*');
+    const matched = tasks.filter((t) => {
+        if (hasWildcard)
+            return true;
+        if (!t.skill_required)
+            return true;
+        return agent.skills.includes(t.skill_required);
+    });
+    matched.sort((a, b) => {
+        if (a.priority !== b.priority)
+            return a.priority - b.priority;
+        return a.sort_order - b.sort_order;
+    });
+    return matched.slice(0, agent.maxConcurrent);
+}
+/**
+ * Finds the first idle agent whose skills match the task's skill_required.
+ * Returns null if no suitable idle agent exists.
+ */
+export function findBestAgent(profiles, task) {
+    for (const agent of profiles) {
+        if (agent.status !== 'idle')
+            continue;
+        if (agent.skills.includes('*'))
+            return agent;
+        if (!task.skill_required)
+            return agent;
+        if (agent.skills.includes(task.skill_required))
+            return agent;
+    }
+    return null;
+}

package/dist/lib/config/registry.d.ts

@@ -0,0 +1,17 @@
+import { getSupabase } from '../supabase.js';
+import { type OptimalConfigV1 } from './schema.js';
+export declare function setRegistrySupabaseProviderForTests(provider: typeof getSupabase): void;
+export declare function resetRegistrySupabaseProviderForTests(): void;
+export declare function ensureConfigDir(): Promise<void>;
+export declare function getLocalConfigPath(): string;
+export declare function getHistoryPath(): string;
+export declare function readLocalConfig(): Promise<OptimalConfigV1 | null>;
+export declare function writeLocalConfig(config: OptimalConfigV1): Promise<void>;
+export declare function hashConfig(config: OptimalConfigV1): string;
+export declare function appendHistory(entry: string): Promise<void>;
+export type RegistrySyncResult = {
+    ok: boolean;
+    message: string;
+};
+export declare function pullRegistryProfile(profile?: string): Promise<RegistrySyncResult>;
+export declare function pushRegistryProfile(profile?: string, force?: boolean, agent?: string): Promise<RegistrySyncResult>;

package/dist/lib/config/registry.js

@@ -0,0 +1,182 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { getSupabase } from '../supabase.js';
+import { assertOptimalConfigV1 } from './schema.js';
+const DIR = join(homedir(), '.optimal');
+const LOCAL_CONFIG_PATH = join(DIR, 'optimal.config.json');
+const HISTORY_PATH = join(DIR, 'config-history.log');
+const REGISTRY_TABLE = 'cli_config_registry';
+let supabaseProvider = getSupabase;
+function getGlobalProviderOverride() {
+    const candidate = globalThis.__optimalRegistrySupabaseProvider;
+    return candidate ?? null;
+}
+function getActiveSupabaseProvider() {
+    return getGlobalProviderOverride() ?? supabaseProvider;
+}
+export function setRegistrySupabaseProviderForTests(provider) {
+    supabaseProvider = provider;
+    globalThis.__optimalRegistrySupabaseProvider = provider;
+}
+export function resetRegistrySupabaseProviderForTests() {
+    supabaseProvider = getSupabase;
+    delete globalThis.__optimalRegistrySupabaseProvider;
+}
+export async function ensureConfigDir() {
+    await mkdir(DIR, { recursive: true });
+}
+export function getLocalConfigPath() {
+    return LOCAL_CONFIG_PATH;
+}
+export function getHistoryPath() {
+    return HISTORY_PATH;
+}
+export async function readLocalConfig() {
+    if (!existsSync(LOCAL_CONFIG_PATH))
+        return null;
+    const raw = await readFile(LOCAL_CONFIG_PATH, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return assertOptimalConfigV1(parsed);
+}
+export async function writeLocalConfig(config) {
+    await ensureConfigDir();
+    await writeFile(LOCAL_CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
+}
+export function hashConfig(config) {
+    const payload = JSON.stringify(config);
+    return createHash('sha256').update(payload).digest('hex');
+}
+export async function appendHistory(entry) {
+    await ensureConfigDir();
+    await writeFile(HISTORY_PATH, `${entry}\n`, { encoding: 'utf-8', flag: 'a' });
+}
+function resolveOwner(local) {
+    return local?.profile.owner || process.env.OPTIMAL_CONFIG_OWNER || null;
+}
+function parseEpoch(input) {
+    if (!input)
+        return 0;
+    const ts = Date.parse(input);
+    return Number.isNaN(ts) ? 0 : ts;
+}
+export async function pullRegistryProfile(profile = 'default') {
+    try {
+        const local = await readLocalConfig();
+        const owner = resolveOwner(local);
+        if (!owner) {
+            return {
+                ok: false,
+                message: 'registry pull failed: missing owner (set local config profile.owner or OPTIMAL_CONFIG_OWNER)',
+            };
+        }
+        const supabase = getActiveSupabaseProvider()('optimal');
+        const { data, error } = await supabase
+            .from(REGISTRY_TABLE)
+            .select('owner,profile,config_version,payload,payload_hash,updated_at')
+            .eq('owner', owner)
+            .eq('profile', profile)
+            .maybeSingle();
+        if (error) {
+            return { ok: false, message: `registry pull failed: ${error.message}` };
+        }
+        if (!data) {
+            return { ok: false, message: `registry pull failed: no remote profile found for owner=${owner} profile=${profile}` };
+        }
+        const row = data;
+        const payload = assertOptimalConfigV1(row.payload);
+        await writeLocalConfig(payload);
+        const localHash = local ? hashConfig(local) : null;
+        const changed = localHash !== row.payload_hash;
+        return {
+            ok: true,
+            message: changed
+                ? `registry pull ok: wrote owner=${owner} profile=${profile} hash=${row.payload_hash.slice(0, 12)}`
+                : `registry pull ok: local already matched owner=${owner} profile=${profile}`,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            message: `registry pull failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+export async function pushRegistryProfile(profile = 'default', force = false, agent) {
+    try {
+        const local = await readLocalConfig();
+        if (!local) {
+            return { ok: false, message: `registry push failed: no local config at ${LOCAL_CONFIG_PATH}` };
+        }
+        let owner = resolveOwner(local);
+        if (!owner && agent) {
+            owner = agent;
+            local.profile.owner = owner;
+        }
+        if (!owner) {
+            return {
+                ok: false,
+                message: 'registry push failed: missing owner (set local config profile.owner, OPTIMAL_CONFIG_OWNER, or use --agent)',
+            };
+        }
+        const localHash = hashConfig(local);
+        const supabase = getActiveSupabaseProvider()('optimal');
+        const { data: existing, error: readErr } = await supabase
+            .from(REGISTRY_TABLE)
+            .select('owner,profile,config_version,payload,payload_hash,updated_at')
+            .eq('owner', owner)
+            .eq('profile', profile)
+            .maybeSingle();
+        if (readErr) {
+            return { ok: false, message: `registry push failed: ${readErr.message}` };
+        }
+        if (existing) {
+            const row = existing;
+            if (row.payload_hash !== localHash && !force) {
+                const remotePayload = assertOptimalConfigV1(row.payload);
+                const remoteTs = Math.max(parseEpoch(row.updated_at), parseEpoch(remotePayload.profile.updated_at));
+                const localTs = parseEpoch(local.profile.updated_at);
+                if (remoteTs >= localTs) {
+                    return {
+                        ok: false,
+                        message: `registry push conflict: remote is newer/different for owner=${owner} profile=${profile}. ` +
+                            'run `optimal config sync pull` or retry with --force',
+                    };
+                }
+            }
+        }
+        const payload = {
+            ...local,
+            profile: {
+                ...local.profile,
+                name: profile,
+                owner,
+                updated_at: new Date().toISOString(),
+            },
+        };
+        const { error: upsertErr } = await supabase.from(REGISTRY_TABLE).upsert({
+            owner,
+            profile,
+            config_version: payload.version,
+            payload,
+            payload_hash: hashConfig(payload),
+            source: 'optimal-cli',
+            updated_by: process.env.USER || 'oracle',
+        }, { onConflict: 'owner,profile' });
+        if (upsertErr) {
+            return { ok: false, message: `registry push failed: ${upsertErr.message}` };
+        }
+        return {
+            ok: true,
+            message: `registry push ok: owner=${owner} profile=${profile} hash=${hashConfig(payload).slice(0, 12)} force=${force}`,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            message: `registry push failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}

package/dist/lib/config/schema.d.ts

@@ -0,0 +1,31 @@
+export type ConfigSchemaVersion = '1.0.0';
+export interface OptimalConfigV1 {
+    version: ConfigSchemaVersion;
+    profile: {
+        name: string;
+        owner: string;
+        updated_at: string;
+    };
+    providers: {
+        supabase: {
+            project_ref: string;
+            url: string;
+            anon_key_present: boolean;
+        };
+        strapi: {
+            base_url: string;
+            token_present: boolean;
+        };
+    };
+    defaults: {
+        brand: string;
+        timezone: string;
+    };
+    features: {
+        cms: boolean;
+        tasks: boolean;
+        deploy: boolean;
+    };
+}
+export declare function isOptimalConfigV1(value: unknown): value is OptimalConfigV1;
+export declare function assertOptimalConfigV1(value: unknown): OptimalConfigV1;

package/dist/lib/config/schema.js

@@ -0,0 +1,25 @@
+export function isOptimalConfigV1(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (v.version === '1.0.0' &&
+        typeof v.profile?.name === 'string' &&
+        typeof v.profile?.owner === 'string' &&
+        typeof v.profile?.updated_at === 'string' &&
+        typeof v.providers?.supabase?.project_ref === 'string' &&
+        typeof v.providers?.supabase?.url === 'string' &&
+        typeof v.providers?.supabase?.anon_key_present === 'boolean' &&
+        typeof v.providers?.strapi?.base_url === 'string' &&
+        typeof v.providers?.strapi?.token_present === 'boolean' &&
+        typeof v.defaults?.brand === 'string' &&
+        typeof v.defaults?.timezone === 'string' &&
+        typeof v.features?.cms === 'boolean' &&
+        typeof v.features?.tasks === 'boolean' &&
+        typeof v.features?.deploy === 'boolean');
+}
+export function assertOptimalConfigV1(value) {
+    if (!isOptimalConfigV1(value)) {
+        throw new Error('Invalid optimal config payload (v1)');
+    }
+    return value;
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Centralized error handling for the Optimal CLI.
+ *
+ * Provides a typed CliError class, a user-friendly formatter,
+ * and a wrapCommand helper for Commander action handlers.
+ */
+export type ErrorCode = 'MISSING_ENV' | 'NOT_FOUND' | 'SUPABASE_ERROR' | 'VALIDATION_ERROR' | 'AUTH_ERROR' | 'NETWORK_ERROR' | 'FILE_ERROR' | 'UNKNOWN';
+export declare class CliError extends Error {
+    code: ErrorCode;
+    suggestion?: string | undefined;
+    constructor(message: string, code: ErrorCode, suggestion?: string | undefined);
+}
+/**
+ * Format an error for CLI output, print it to stderr, and exit with code 1.
+ */
+export declare function handleError(err: unknown): never;
+/**
+ * Wrap a Commander action handler so any thrown error is routed through
+ * handleError, giving the user a consistent, friendly message instead of
+ * an unhandled-rejection stack trace.
+ *
+ * Usage:
+ *   .action(wrapCommand(async (opts) => { ... }))
+ */
+export declare function wrapCommand<A extends unknown[]>(fn: (...args: A) => Promise<void>): (...args: A) => Promise<void>;

package/dist/lib/errors.js

@@ -0,0 +1,91 @@
+/**
+ * Centralized error handling for the Optimal CLI.
+ *
+ * Provides a typed CliError class, a user-friendly formatter,
+ * and a wrapCommand helper for Commander action handlers.
+ */
+// ── CliError ─────────────────────────────────────────────────────────────────
+export class CliError extends Error {
+    code;
+    suggestion;
+    constructor(message, code, suggestion) {
+        super(message);
+        this.code = code;
+        this.suggestion = suggestion;
+        this.name = 'CliError';
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+const SUGGESTIONS = {
+    MISSING_ENV: 'Ensure the required environment variables are set in your .env file or shell.',
+    NOT_FOUND: 'Double-check the identifier (slug, ID, or name) and try again.',
+    SUPABASE_ERROR: 'Verify your Supabase URL and service key are correct and the database is reachable.',
+    VALIDATION_ERROR: 'Review the command options with --help.',
+    AUTH_ERROR: 'Check your API token or credentials and make sure they have not expired.',
+    NETWORK_ERROR: 'Check your internet connection and verify the remote service is available.',
+    FILE_ERROR: 'Verify the file path exists and you have read/write permissions.',
+};
+function classifyError(err) {
+    if (err instanceof CliError) {
+        return { code: err.code, message: err.message };
+    }
+    if (err instanceof Error) {
+        const msg = err.message;
+        // Supabase / fetch errors
+        if (msg.includes('PGRST') || msg.includes('supabase') || msg.includes('relation')) {
+            return { code: 'SUPABASE_ERROR', message: msg };
+        }
+        if (msg.includes('ENOENT') || msg.includes('no such file')) {
+            return { code: 'FILE_ERROR', message: msg };
+        }
+        if (msg.includes('ECONNREFUSED') || msg.includes('fetch failed') || msg.includes('ETIMEDOUT')) {
+            return { code: 'NETWORK_ERROR', message: msg };
+        }
+        if (msg.includes('OPTIMAL_SUPABASE_URL') ||
+            msg.includes('OPTIMAL_SUPABASE_SERVICE_KEY') ||
+            msg.includes('env')) {
+            return { code: 'MISSING_ENV', message: msg };
+        }
+        return { code: 'UNKNOWN', message: msg };
+    }
+    return { code: 'UNKNOWN', message: String(err) };
+}
+// ── handleError ──────────────────────────────────────────────────────────────
+/**
+ * Format an error for CLI output, print it to stderr, and exit with code 1.
+ */
+export function handleError(err) {
+    const { code, message } = classifyError(err);
+    const suggestion = err instanceof CliError && err.suggestion
+        ? err.suggestion
+        : SUGGESTIONS[code] ?? '';
+    const lines = [
+        '',
+        `  Error [${code}]: ${message}`,
+    ];
+    if (suggestion) {
+        lines.push(`  Suggestion: ${suggestion}`);
+    }
+    lines.push('');
+    process.stderr.write(lines.join('\n'));
+    process.exit(1);
+}
+// ── wrapCommand ──────────────────────────────────────────────────────────────
+/**
+ * Wrap a Commander action handler so any thrown error is routed through
+ * handleError, giving the user a consistent, friendly message instead of
+ * an unhandled-rejection stack trace.
+ *
+ * Usage:
+ *   .action(wrapCommand(async (opts) => { ... }))
+ */
+export function wrapCommand(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            handleError(err);
+        }
+    };
+}

package/dist/lib/format.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Lightweight CLI output formatting — ANSI colors, tables, badges.
+ * Zero external dependencies. Respects NO_COLOR env var.
+ */
+type Color = 'red' | 'green' | 'yellow' | 'blue' | 'cyan' | 'gray' | 'bold' | 'dim';
+/**
+ * Wrap text in ANSI escape codes for the given color/style.
+ * Returns plain text when NO_COLOR env var is set.
+ */
+export declare function colorize(text: string, color: Color): string;
+/**
+ * Render a bordered ASCII table with auto-sized columns.
+ * Headers are rendered in bold.
+ */
+export declare function table(headers: string[], rows: string[][]): string;
+/** Return a colored status string (e.g. "done" in green). */
+export declare function statusBadge(status: string): string;
+/** Return a colored priority label (e.g. "P1" in red). */
+export declare function priorityBadge(p: number): string;
+/** Print a green success message with a check mark prefix. */
+export declare function success(msg: string): void;
+/** Print a red error message with an X prefix. */
+export declare function error(msg: string): void;
+/** Print a yellow warning message with a warning prefix. */
+export declare function warn(msg: string): void;
+/** Print a blue info message with an info prefix. */
+export declare function info(msg: string): void;
+export {};