@arcadialdev/arcality 2.2.0

package/src/arcalityClient.mjs

@@ -0,0 +1,266 @@
+// src/arcalityClient.mjs
+// Client for communicating with Arcality Backend
+// Supports arcality.config (primary) and .env (fallback)
+// Includes MOCK MODE for development without backend
+import fs from 'node:fs';
+import path from 'node:path';
+import { getApiKey, getApiUrl, CONFIG_DIR } from './configLoader.mjs';
+
+// ── Backend config (internal, not user-configurable) ──
+const DAILY_MISSION_LIMIT = 50;
+const USAGE_FILE = path.join(CONFIG_DIR, 'usage.json');
+
+// ═══════════════════════════════════════════════════════
+// MOCK MODE: Local simulation (no backend)
+// Tracks daily usage in ~/.arcality/usage.json
+// ═══════════════════════════════════════════════════════
+
+function getTodayKey() {
+    return new Date().toISOString().slice(0, 10);
+}
+
+function loadLocalUsage() {
+    try {
+        if (fs.existsSync(USAGE_FILE)) {
+            return JSON.parse(fs.readFileSync(USAGE_FILE, 'utf8'));
+        }
+    } catch { }
+    return {};
+}
+
+function saveLocalUsage(usage) {
+    try {
+        if (!fs.existsSync(CONFIG_DIR)) {
+            fs.mkdirSync(CONFIG_DIR, { recursive: true });
+        }
+        fs.writeFileSync(USAGE_FILE, JSON.stringify(usage, null, 2), 'utf8');
+    } catch { }
+}
+
+function getLocalDailyUsage() {
+    const usage = loadLocalUsage();
+    const today = getTodayKey();
+    return usage[today] || 0;
+}
+
+function incrementLocalUsage() {
+    const usage = loadLocalUsage();
+    const today = getTodayKey();
+    usage[today] = (usage[today] || 0) + 1;
+
+    const keys = Object.keys(usage).sort().reverse();
+    const cleaned = {};
+    for (const k of keys.slice(0, 7)) {
+        cleaned[k] = usage[k];
+    }
+    saveLocalUsage(cleaned);
+    return cleaned[today];
+}
+
+// ═══════════════════════════════════════════════════════
+// ARCALITY CONFIG LOADER (for reading arcality.config directly)
+// ═══════════════════════════════════════════════════════
+
+function loadArcalityConfig() {
+    try {
+        const configPath = path.join(process.cwd(), 'arcality.config');
+        if (fs.existsSync(configPath)) {
+            let raw = fs.readFileSync(configPath, 'utf8');
+            if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+            return JSON.parse(raw);
+        }
+    } catch { }
+    return null;
+}
+
+/**
+ * Gets the effective API base URL.
+ * Uses the internal getApiUrl() — NOT configurable by user.
+ */
+function getEffectiveApiBase() {
+    return getApiUrl();
+}
+
+/**
+ * Gets the effective API Key.
+ * Priority: arcality.config > env > global config
+ */
+function getEffectiveApiKey() {
+    const localConfig = loadArcalityConfig();
+    if (localConfig?.apiKey) return localConfig.apiKey;
+
+    const { key } = getApiKey();
+    return key;
+}
+
+// ═══════════════════════════════════════════════════════
+// PUBLIC API
+// ═══════════════════════════════════════════════════════
+
+/**
+ * ArcalityClient class — used by KnowledgeService and other modules.
+ */
+export class ArcalityClient {
+    constructor(apiKey) {
+        this.apiUrl = getApiUrl();
+        this.apiKey = apiKey;
+    }
+}
+
+/**
+ * Validates the API Key.
+ * - If backend is available (ARCALITY_API_URL) → validates remotely
+ * - If no backend → mock mode with local validation
+ */
+export async function validateApiKey() {
+    const key = getEffectiveApiKey();
+
+    if (!key) {
+        return { valid: false, error: 'no_api_key', mode: 'mock' };
+    }
+
+    if (!key.startsWith('arc_k_')) {
+        return { valid: false, error: 'invalid_format', mode: 'mock' };
+    }
+
+    const apiBase = getEffectiveApiBase();
+
+    // ── LIVE mode: Backend available ──
+    if (apiBase) {
+        try {
+            const res = await fetch(`${apiBase}/api/v1/auth/validate`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': key
+                }
+            });
+
+            if (res.status === 401) return { valid: false, error: 'invalid_api_key', mode: 'live' };
+            if (res.status === 403) return { valid: false, error: 'plan_expired', mode: 'live' };
+            if (!res.ok) return { valid: false, error: 'server_error', mode: 'live' };
+
+            const data = await res.json();
+            return { ...data, valid: true, mode: 'live' };
+        } catch {
+            console.warn('⚠️  Backend not available, using local mode');
+        }
+    }
+
+    // ── MOCK mode: No backend ──
+    const dailyUsed = getLocalDailyUsage();
+    return {
+        valid: true,
+        mode: 'mock',
+        plan: 'internal',
+        daily_used: dailyUsed,
+        daily_limit: DAILY_MISSION_LIMIT,
+        remaining: Math.max(0, DAILY_MISSION_LIMIT - dailyUsed)
+    };
+}
+
+/**
+ * Requests to start a mission.
+ * @param {string} prompt - The mission prompt (only a hash is sent, never the raw text)
+ * @param {string} targetUrl - Target portal URL
+ */
+export async function startMission(prompt, targetUrl) {
+    const key = getEffectiveApiKey();
+    if (!key) return { allowed: false, error: 'no_api_key' };
+
+    const apiBase = getEffectiveApiBase();
+
+    // ── LIVE mode ──
+    if (apiBase) {
+        try {
+            const projectId = process.env.ARCALITY_PROJECT_ID || loadArcalityConfig()?.projectId;
+
+            const res = await fetch(`${apiBase}/api/v1/missions/start`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': key
+                },
+                body: JSON.stringify({
+                    prompt_hash: simpleHash(prompt),
+                    target_url: targetUrl,
+                    project_id: projectId || undefined,
+                })
+            });
+
+            if (res.status === 429) {
+                const data = await res.json();
+                return { allowed: false, error: 'mission_limit_exceeded', ...data };
+            }
+            if (!res.ok) return { allowed: false, error: 'server_error' };
+
+            return { allowed: true, ...(await res.json()) };
+        } catch {
+            // Fallback to mock if backend is down
+        }
+    }
+
+    // ── MOCK mode ──
+    const dailyUsed = getLocalDailyUsage();
+
+    if (dailyUsed >= DAILY_MISSION_LIMIT) {
+        const tomorrow = new Date();
+        tomorrow.setDate(tomorrow.getDate() + 1);
+        tomorrow.setHours(0, 0, 0, 0);
+
+        return {
+            allowed: false,
+            error: 'mission_limit_exceeded',
+            daily_used: dailyUsed,
+            daily_limit: DAILY_MISSION_LIMIT,
+            remaining: 0,
+            resets_at: tomorrow.toISOString()
+        };
+    }
+
+    const newCount = incrementLocalUsage();
+    return {
+        allowed: true,
+        mode: 'mock',
+        mission_id: `mock_${Date.now().toString(36)}`,
+        daily_used: newCount,
+        daily_limit: DAILY_MISSION_LIMIT,
+        remaining: DAILY_MISSION_LIMIT - newCount
+    };
+}
+
+/**
+ * Marks a mission as completed.
+ * @param {string} missionId
+ * @param {'success'|'failed'|'cancelled'} result
+ */
+export async function endMission(missionId, result) {
+    const apiBase = getEffectiveApiBase();
+    if (!apiBase || !missionId) return { ok: true };
+
+    const key = getEffectiveApiKey();
+    try {
+        await fetch(`${apiBase}/api/v1/missions/${missionId}/end`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': key
+            },
+            body: JSON.stringify({ result })
+        });
+    } catch { }
+    return { ok: true };
+}
+
+/**
+ * Simple hash of the prompt — we never send the raw text to backend
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash |= 0;
+    }
+    return 'ph_' + Math.abs(hash).toString(36);
+}

package/src/configLoader.mjs

@@ -0,0 +1,179 @@
+// src/configLoader.mjs
+// Configuration loader — supports arcality.config (primary) and .env / global config (fallback)
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+export const CONFIG_DIR = path.join(os.homedir(), '.arcality');
+export const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+/**
+ * Returns the internal API URL for the Arcality backend.
+ * This is loaded exclusively from the tool's .env file (via dotenv).
+ * It is NOT configurable by the user, CLI flags, or arcality.config.
+ * To change it, modify the ARCALITY_API_URL variable in the tool's .env.
+ * @returns {string}
+ */
+export function getApiUrl() {
+    return process.env.ARCALITY_API_URL || 'http://localhost:5164';
+}
+
+/**
+ * Loads the local arcality.config file from cwd (if it exists).
+ * @returns {object|null}
+ */
+function loadLocalArcalityConfig() {
+    try {
+        const configPath = path.join(process.cwd(), 'arcality.config');
+        if (fs.existsSync(configPath)) {
+            let raw = fs.readFileSync(configPath, 'utf8');
+            if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+            return JSON.parse(raw);
+        }
+    } catch { }
+    return null;
+}
+
+/**
+ * Loads configuration from multiple sources:
+ *   1. arcality.config (local project config — highest priority)
+ *   2. .env (environment variables)
+ *   3. ~/.arcality/config.json (global config)
+ * 
+ * NOTE: ARCALITY_API_URL is NOT included here — use getApiUrl() instead.
+ * 
+ * @returns {{
+ *   ARCALITY_API_KEY: string,
+ *   ARCALITY_PROJECT_ID?: string
+ * }}
+ */
+export function loadConfig() {
+    const localConfig = loadLocalArcalityConfig();
+    const globalConfig = loadGlobalConfig();
+
+    const config = {
+        ARCALITY_API_KEY: localConfig?.apiKey || process.env.ARCALITY_API_KEY || globalConfig?.api_key,
+        ARCALITY_PROJECT_ID: localConfig?.projectId || process.env.ARCALITY_PROJECT_ID,
+    };
+
+    if (!config.ARCALITY_API_KEY) {
+        throw new Error('ARCALITY_API_KEY is not defined. Run `arcality init` or set it in your .env file.');
+    }
+
+    return config;
+}
+
+
+/**
+ * Reads the user's global config (~/.arcality/config.json)
+ * @returns {{ api_key?: string, install_dir?: string, version?: string } | null}
+ */
+export function loadGlobalConfig() {
+    try {
+        if (fs.existsSync(CONFIG_FILE)) {
+            let raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+            // Strip BOM that PowerShell adds with -Encoding UTF8
+            if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+            return JSON.parse(raw);
+        }
+    } catch { }
+    return null;
+}
+
+/**
+ * Saves/updates the user's global config
+ * @param {object} updates - Fields to update
+ */
+export function saveGlobalConfig(updates) {
+    try {
+        if (!fs.existsSync(CONFIG_DIR)) {
+            fs.mkdirSync(CONFIG_DIR, { recursive: true });
+        }
+        const existing = loadGlobalConfig() || {};
+        const merged = { ...existing, ...updates };
+        fs.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), 'utf8');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Gets the API Key (priority: arcality.config > env var > global config)
+ * @returns {{ key: string | null, source: 'config' | 'env' | 'global' | 'none' }}
+ */
+export function getApiKey() {
+    // 1. Local arcality.config
+    const localConfig = loadLocalArcalityConfig();
+    if (localConfig?.apiKey) {
+        process.env.ARCALITY_API_KEY = localConfig.apiKey;
+        return { key: localConfig.apiKey, source: 'config' };
+    }
+
+    // 2. Environment variable (.env or shell)
+    if (process.env.ARCALITY_API_KEY) {
+        return { key: process.env.ARCALITY_API_KEY, source: 'env' };
+    }
+
+    // 3. Global config ~/.arcality/config.json
+    const globalCfg = loadGlobalConfig();
+    if (globalCfg?.api_key) {
+        process.env.ARCALITY_API_KEY = globalCfg.api_key;
+        return { key: globalCfg.api_key, source: 'global' };
+    }
+
+    return { key: null, source: 'none' };
+}
+
+/**
+ * Loads additional secrets (like Anthropic) from global config
+ */
+export function setupProcessEnv() {
+    const config = loadGlobalConfig();
+    if (!config) return;
+
+    // Load Arcality API Key
+    getApiKey();
+
+    // Load Anthropic API Key if not already in env
+    if (config.anthropic_api_key && !process.env.ANTHROPIC_API_KEY) {
+        process.env.ANTHROPIC_API_KEY = config.anthropic_api_key;
+    }
+
+    // Load default model if exists
+    if (config.model && !process.env.CLAUDE_MODEL) {
+        process.env.CLAUDE_MODEL = config.model;
+    }
+
+    // Also inject arcality.config values into process.env for backward compat
+    const localConfig = loadLocalArcalityConfig();
+    if (localConfig) {
+        if (localConfig.apiKey && !process.env.ARCALITY_API_KEY) {
+            process.env.ARCALITY_API_KEY = localConfig.apiKey;
+        }
+        if (localConfig.projectId && !process.env.ARCALITY_PROJECT_ID) {
+            process.env.ARCALITY_PROJECT_ID = localConfig.projectId;
+        }
+        if (localConfig.project?.baseUrl && !process.env.BASE_URL) {
+            process.env.BASE_URL = localConfig.project.baseUrl;
+        }
+        if (localConfig.auth?.username && !process.env.LOGIN_USER) {
+            process.env.LOGIN_USER = localConfig.auth.username;
+        }
+        if (localConfig.auth?.password && !process.env.LOGIN_PASSWORD) {
+            process.env.LOGIN_PASSWORD = localConfig.auth.password;
+        }
+    }
+}
+
+/**
+ * Visual mask of API Key for banner display
+ * "arc_k_live_abc123xyz" → "arc_k_****xyz"
+ */
+export function maskApiKey(key) {
+    if (!key || key.length < 8) return '***';
+    return key.slice(0, 6) + '****' + key.slice(-4);
+}

package/src/configManager.mjs

@@ -0,0 +1,172 @@
+// src/configManager.mjs
+// Manages the local arcality.config file — single configuration per project.
+// Replaces multi-config .env approach.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CONFIG_FILENAME = 'arcality.config';
+
+/**
+ * Resolves the path to arcality.config in the project root.
+ * @param {string} [projectRoot] - Override project root. Defaults to cwd.
+ * @returns {string}
+ */
+export function getConfigPath(projectRoot) {
+    return path.join(projectRoot || process.cwd(), CONFIG_FILENAME);
+}
+
+/**
+ * Checks if arcality.config exists in the project.
+ * @param {string} [projectRoot]
+ * @returns {boolean}
+ */
+export function configExists(projectRoot) {
+    return fs.existsSync(getConfigPath(projectRoot));
+}
+
+/**
+ * Reads and parses the arcality.config file.
+ * @param {string} [projectRoot]
+ * @returns {ArcalityConfig | null}
+ */
+export function loadProjectConfig(projectRoot) {
+    const configPath = getConfigPath(projectRoot);
+    try {
+        if (!fs.existsSync(configPath)) return null;
+        let raw = fs.readFileSync(configPath, 'utf8');
+        // Strip BOM if present
+        if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+        return JSON.parse(raw);
+    } catch (err) {
+        console.error(`⚠️  Error reading ${CONFIG_FILENAME}: ${err.message}`);
+        return null;
+    }
+}
+
+/**
+ * Writes the arcality.config file.
+ * @param {ArcalityConfig} config
+ * @param {string} [projectRoot]
+ */
+export function saveProjectConfig(config, projectRoot) {
+    const configPath = getConfigPath(projectRoot);
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+}
+
+/**
+ * Validates that the config has all required fields for running.
+ * @param {ArcalityConfig} config
+ * @returns {{ valid: boolean, missing: string[] }}
+ */
+export function validateConfig(config) {
+    const missing = [];
+
+    if (!config) {
+        return { valid: false, missing: ['arcality.config file'] };
+    }
+
+    if (!config.apiKey) missing.push('apiKey');
+    if (!config.projectId) missing.push('projectId');
+    if (!config.project?.baseUrl) missing.push('project.baseUrl');
+    if (!config.auth?.username) missing.push('auth.username');
+    if (!config.auth?.password) missing.push('auth.password');
+
+    return { valid: missing.length === 0, missing };
+}
+
+/**
+ * Creates a fresh arcality.config structure.
+ * @param {object} params
+ * @returns {ArcalityConfig}
+ */
+export function createConfig({
+    apiKey,
+    organizationId,
+    projectId,
+    projectName,
+    baseUrl,
+    frameworkDetected,
+    username,
+    password,
+    arcalityVersion,
+    yamlOutputDir = './arcality',
+}) {
+    return {
+        version: '1',
+        apiKey,
+        organizationId: organizationId || null,
+        projectId,
+        project: {
+            name: projectName,
+            baseUrl,
+            frameworkDetected: frameworkDetected || null,
+        },
+        auth: {
+            username,
+            password,
+        },
+        runtime: {
+            yamlOutputDir,
+            reuseSuccessfulYamls: true,
+            singleConfigurationMode: true,
+        },
+        meta: {
+            arcalityVersion: arcalityVersion || 'unknown',
+        },
+    };
+}
+
+/**
+ * Injects arcality.config values into process.env for backward compat
+ * with existing modules that read from process.env.
+ * @param {ArcalityConfig} config
+ */
+export function injectConfigToEnv(config) {
+    if (!config) return;
+
+    if (config.apiKey) process.env.ARCALITY_API_KEY = config.apiKey;
+    if (config.projectId) process.env.ARCALITY_PROJECT_ID = config.projectId;
+    if (config.project?.baseUrl) {
+        process.env.BASE_URL = config.project.baseUrl;
+    }
+    if (config.auth?.username) process.env.LOGIN_USER = config.auth.username;
+    if (config.auth?.password) process.env.LOGIN_PASSWORD = config.auth.password;
+}
+
+/**
+ * Gets the YAML output directory from config, falling back to default.
+ * @param {ArcalityConfig} config
+ * @param {string} [projectRoot]
+ * @returns {string} absolute path
+ */
+export function getYamlOutputDir(config, projectRoot) {
+    const dir = config?.runtime?.yamlOutputDir || './arcality';
+    return path.resolve(projectRoot || process.cwd(), dir);
+}
+
+/**
+ * Ensures the YAML output directory exists.
+ * @param {ArcalityConfig} config
+ * @param {string} [projectRoot]
+ * @returns {string} absolute path to the directory
+ */
+export function ensureYamlOutputDir(config, projectRoot) {
+    const dir = getYamlOutputDir(config, projectRoot);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+
+/**
+ * @typedef {object} ArcalityConfig
+ * @property {string} version
+ * @property {string} apiKey
+ * @property {string|null} organizationId
+ * @property {string} projectId
+ * @property {{ name: string, baseUrl: string, frameworkDetected: string|null }} project
+ * @property {{ username: string, password: string }} auth
+ * @property {{ yamlOutputDir: string, reuseSuccessfulYamls: boolean, singleConfigurationMode: boolean }} runtime
+ * @property {{ arcalityVersion: string }} meta
+ */

package/src/consoleBanner.ts

@@ -0,0 +1,32 @@
+import figlet from 'figlet';
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { intro, note } from '@clack/prompts';
+
+export function showBanner(): void {
+  const projectName = 'Arcality';
+  const subtitle = 'Powered by Arcadial';
+
+  let version = 'unknown';
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+    version = pkg.version || 'unknown';
+  } catch { }
+
+  const logo = figlet.textSync(projectName, {
+    font: 'Standard',
+    horizontalLayout: 'default',
+    verticalLayout: 'default',
+  });
+
+  intro(chalk.cyanBright(logo));
+
+  note(
+    chalk.magentaBright(subtitle) + '\n' +
+    chalk.gray('─'.repeat(50)) + '\n' +
+    chalk.bold.white('📦 Version: ') + chalk.yellow(version) + '\n' +
+    chalk.bold.white('⚙️  Environment: ') + chalk.yellow(process.env.NODE_ENV ?? 'development'),
+    'System Information'
+  );
+}